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RADIO AND TELEVISION INTERFERENCE 

The equipment described in this manual generates and uses radio 
frequency energy. If it is not installed and used properly, that is 
in strict accordance with our instruction©, it nay cause interference 
to radio and television reception* 

This equipment has been tested and complies with the limits for a 
Class B computing device in accordance with the specifications In 
Subpart J of Part 15 of FCC rules. These rules are designed tn 
provide reasonable protection against such interference in a 
residential installation. However^ there Is no guarantee that the 

interference will not occur in a particular installation. 

You can determine whether your coaputer Is causing Interference by 
turning it off. If the interference stops* it was probably caused by 
the computer. If your computer does cause interference to radio or 
television reception, you can try to correct the interference by 
using one or more of the following measures: 

- Turn the TV or radio antenna until the interference stops. 

- Move the computer to one side or the other of the TV or radio. 

- Move the computer farther away frora the TV or radio* 

- Plug the computer into an outlet that is on a different circuit 

from the TV or radio. (That is, make certain the computer and the TV 
or radio are on circuits controlled by different circuit breakers or 
fuses.) 

If necessary, you should consult your dealer or an experienced 

radio/television technician for additional suggestions. You may find 

the following booklet prepared by the Federal Communications 
Commission helpful: 

"How to Identify and Resolve Radio-TV Interference Problems*' 

This booklet is available from the U.S. Government Printing Office, 
Washington^ DC 20402, Stock number «4-<JW-W345-4. 



ST ^ 

» 3 



•s=s 
spa 



p 3 



Co 



PREFACE 

This manual has two primary functions. The first is to teach you how 
use the DOS (Disk Operating System); the Chapters of the manual use 
examples to accompany explanations of how the various DOS commands work. 
The second function of the manual is to serve as a reference guide to 

2?ffc JS* £PP en ? ice V Q* 1( * Reference Card, and the Indices were planned 
with this function in mind. 

To use an Apple Disk II, you need An Apple II coaputer with at least 16K 
of memory — but 32K is recommended, since the 16K system allows littls 

memory space to store programs. In fact* the HDFF1S program and the FID 
program on your System Master Diskette need 32IC of memory to mn. 
using Apple Disk II with Applesoft on casette tape or on diskette, 

computer must have at least 32K of reraory. 



For 

your 



The Apple Disk II is a "floppy" disk rait which allows you to store and 
retrieve information much more quickly and conveniently than you can 
with tape. The information is stored and retrieved from a "diskette" 1 
small (about 5-inch diameter) specially coated plastic disk which is 
permanently sealed In a square plastic case. 



One of the most Important advantages to using Disk II Is that 
information is stored and retrieved by a name under which it is filed, 
program that catalogs phone numbers might be saved with an instruction 



A 
such 

SAVE 



PHONE NUMBERS 

and retrieved with an equally simple command. The name PHOHE NUMBERS 
under which the program is filed is a file name . 

The programs that automatically keep track of files* save and retrieve 
information, and do a multitude of other housekeeping tasks are called 
the Disk Operating System, usually shortened to "DOS". Some people say 
"doss" and others say "dee oh ess". Learning to use DOS and the disk 
consists of learning a few special DOS commands described In this 
manual. These commands can be used as extensions to either Applesoft or 
Integer BASIC or machine language programs. 

At some places you'll see the symbol 

preceding a paragraph. This synfcol indicates an unusual feature to which 
you should be alert. 

The symbol 



E ^ 



precedes paragraphs describing situations from which BASIC may be unable 
to recover. You will lose your program, probably have to re-start DOS, 
and nay have to re-start BASIC. 
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CHAPTER 1 



LLATION AND HANDLING 



*" NOTE *** 



This manual applies to venions of DOS that 
operate In 16 sectors. That is, DOS version 3-3 
and subsequent* If you have an earlier version 
of DOS, It will operate In 13 sectors- To update 
your 13 sector DOS to 16 sectors, change the 
proms on your disk controller card as Instructed 

in Appendix H t and use the MUFFIN program to 

move your data to 16 sector diskettes- To boot 

a 13 sector diskette on yoar 16 sector system, 

use the BASICS Diskette that coms with your Disk II 

or your Disk II Update kit. 



CufUUftctiAf the Cable 
laatalLtnK til* Controller 
tttJtOllit*| Multiple fileW PtIvm 
I tb* £>uk II mnd Disaslid 
jvTtiaa and tagMr/tag Uiafcet-te* 



Under some circumstances, a diskette converted 
by MUFFIN may turn out to be un-runnable- This 
happens when the program on the diskette expects 
to find instructions at specific locations on the 
diskette itself. Host program don't fit that 
category, but a few do- RMacmber* KUFPINing 
a diskette won't harm your 13 sector diskette, 
and you can always boot 13 sector diskettes 

using BASICS, 
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UNPACKING 

Your Disk II system consists of several items- Among these you will find: 



The disk drive (the main box). 

A printed-clrcuit card (the controller 

that plugs into the Apple II. 

A flat ribbon cable* already fastened 

to the disk drive* for connecting 

the disk drive to the controller card. 

A "SYSTEM MASTER" diskette. 

A "BASICS" diskette. 

This manual* 



4) 
5) 

6) 

If you have purchased a drive only (for example* as a second drive for your 
controller card) your system will not include all of the above items- 

Save the packing material in case you wish to transport your disk — or in 
the unlikely event you must return it to your dealer or to the factory Cor 
service. 

*** Special Note *** 

Before connecting or disconnecting 
ANYTHING 
on the Disk II or Apple II 

TURN OFF THE POWER. 
This is a must* 



CONNECTING THE CABLE 



In use* the disk drive will be connected to the controller card by the 
flat* ribbon-like cable. One end of this ribbon cable is already fastened 
to the disk drive. If this is your first disk drive* the connector at the 
end of the ribbon cable fro« this drive should be attached to the upper 

set of pins on the controller card. This set of controller card pins is 
labelled "DRIVE V\ 

*** Caution *** 

If the cable from the disk drive to the controller card is not plugged into 
the controller card correctly, considerable physical damage can be done to 
the disk drive unit and its electronics* To assure correct assembly* be 
sure to plug the ribbon cable into the controller card before installing the 
controller card into the computer* Two installation tips follow* First* 

don't jam the cable between the connector and the controller card. When the 

cable is plugged into the controller card correctly* the cable should exit 
from its connector on the side of the connector that is away from the 
controller card* as shown in the photograph. Second* make sure that all the 
pins of the controller card's connector go into the matching holes in the 
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ribbon ruble's connector. By making the connection before installing the 
mrd, you can actually SM that all the pins are going into the holes 

cornet ly* 
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" Connecting the Cable to the Controller rt 

If you are installing a second disk drive* you should connect the ribbon 

cable from the second drive to the lower set of pins on your controller* 
This set of pins is labeled "DRIVR 2". Take the same care attaching this 

connector as you did with the first- 

If you are updating an earlier version of DOS to sixteen sectors, you will 
need to change two proms on your existing controller card. Read Appendix H 
to find out how to do this. 

INSTALLING THE CONTROLLER 

To install the Disk II controller card, which you have already connected to 

the disk drive via the ribbon cable* you will simply plug the controller 
card into a socket inside the Apple II, as follows: 

1. Turn off the power switch at the back of the Apple II. This is 
important to prevent damage to the computer. If the power is on* removal 

or insertion of any card could cause permanent damage to both the card and 

the Apple II* 

2- Remove the cover from the Apple II. This is done by pulling up on the 
rov(»i fll the rc-ir fiiyy (the *dg€ farthest from the keyboard) until the two 
corner fasteners pop apart- Do not continue to lift the rear edge, but 

slid* the cover backward until It cones free* 

). Inside the Apple II* across the rear of the circuit board* there is a 
row of ciftht long* narrow sockets called "slots"* The leftmost one 

(looking at the computer from the keyboard end) is slot ff0* and the 
rightmost one is slot #7. Locate slot #6, one socket to the left of the 
rightmost socket* The controller card may be placed in any slot except 

■lot I0 t the leftmost* However* Apple's standard location for the disk 
controller card t* slot *n* and most Apple software (and this manual) is 
wrlrifii Willi rlml lor.ninn In mind. 



4. BE SURE THE POWER IS OFF BEFORE YOU INSERT OR REMOVE ANY CARD FROM THE 
COMPUTER. Insert the "fingers" portion of the controller Into slot #6. 
The "fingers" portion will enter the socket with some friction and will 
then seat firmly. Since the fingers make electrical contact, it Is a good 
Idea to keep your fingers from touching thera. Before installation, you 
pay wish to use rubbing alcohol to. clean the fingers on the board (and, 
optionally, your own fingers if you're so inclined). 
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INSTALLING MULTIPLE DISK DRIVES 
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Inserting the Controller Card 

5- Adjust the ribbon cable so it lays flat and passes over one of the 
areas between the vertical openings in the back of the Apple II case, at 
shown in the drawing. When the lid is installed it will clamp down the 
cable and act as a strain reliefs 
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Cable Placement 

6. Replace the cover of the Apple II; remember to start by sliding the 
front edge of the cover into place- Press down on the two rear corners 
until they pop into place. 

7. The Disk II controller is installed, and the Apple II may now be 
turned on. Place the disk drive in a convenient location, usually 
alongside of or on top of your Apple II. 



RS -I 
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Each controller card can be used with two disk drives, one attached to the 
upper set of pins, labeled "DRIVE l'\ and the second attached to the lower 
hvi of pins, labeled "DRIVE 2". Your first disk drive should be attached to 
1 pins and the second to DRIVE 2 pins on the card in slot *6. The 
fourth drives should be attached to the DRIVE 1 and DRIVE 2 pins, 
M-spoct ively, on a card in slot #5, the fifth and sixth drives attach to the 
DRIVE 1 and DRIVE 2 pins on a card In slot #4, and so on- 

If you have multiple drives, it is a good idea to label the front of each 
drive with its slot and drive number since your programs will refer to the 
disks by those numbers. 

CARE OF THE DISK II AND DISKETTES 

The Disk II drive, unlike the Apple II, is a mechanical device, with motors 

and moving parts* Therefore it is somewhat more delicate than the 

computer. Rough handling, such as dropping the drive, or having things 
drop on it, can cause it to malfunction- The drive should not be placed 
beside or on a TV set, since the strong magnetic fields put out by TVs may 
cause damage to the magnetic properties of the drive* If in doubt, locate 
disk drives at least 2 feet from any TV set- 



so 



Each diskette is a small (about 5-inch diameter) plastic disk coated 

that information may be stored on and erased from its surface. The 

coating is similar to the magnetic coating on recording tape. The 

diskette Is permanently sealed in a square black plastic cover which 
protects it, helps keep It clean and allows it to spin freely. This 

package is never opened* 

The term "floppy" comes from the fact that the diskette is flexible. Older 
computer Information storage devices that worked on similar principles 
used rigid disks. While the diskette (and Its plastic cover) are somewhat 
flexible, actually bending the diskette can damage it* The diskette cover 
contains both lubricants and cleaning agents to extend trouble free 
operation - - treat covers with respect* 

Never let anything touch the brown or gray surface of the diskette itself. 
Handle the diskette by the black plastic cover only. When a diskette Is 
not in use, keep it in the paper pocket that it came in. These pockets 

are treated to minimize static build-up which attracts dust. It is best 
to store diskettes vertically when they are not In use. Vinyl notebooks 
especially made for this purpose are convenient. 

Diskettes hold a tremendous amount of information: a single diskette can 

hold over l,U6,000 bits of Information. An individual bit of 

inf ormiition, therefore, occupies a very small portion of the diskette. An 

invisible scratch on the surface of the diskette, or even a fingerprint, 
can cause errors. Do not place diskettes on dirty or greasy surfaces; do 

not let them collect dust- 
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To write on a diskette label, use a PELT 
Is best not to write on a label attached 
the separate label, then attach it to the diskette. 



TIP pen* Do not press hard. It 
to a diskette, but to write on 



Keep diskettes away from magnetic fields- This means to keep then away 
from electric motors and magnets; they should not be placed on top of 
electronic devices such as television sets- They may be temporarily laid 
on the Apple II or the Disk II* 

Diskettes arc sensitive to extremes of temperature* Keep diskettes out of 
the sun, and sway from other sources of heat that can cause them to warp 
and/or lose data. On hot days, car trunks (or dashboards) can be diskette 
killers* Diskettes operate satisfactorily up to 12) degrees Fahrenheit 
(51.7 Celsius), which is not very hot. The first evidence of heat damage 
is a warped or bent block plastic cover. 

With reasonable care a diskette will give you an average life of 40 hours 
— which is a lot, when you consider the few seconds it takes to LOAD most 
programs. With just a little bit of carcle* 
no service at all* 



mess, a diskette may give you 
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INSERTING AND REMOVING DISKETTES 

Using a disk drive is far quicker and easier than using a cassette 
recorder, however some care Is necessary to protect the diskettes. The 
drive itself must also bo handled with some care. The drive door is 
opened by pulling outward on its bottom edge. The diskette Is then 
slipped into the slot with the label upwards , as shown in the 
photograph. The edge of the diskette with the oval cutout in the 
diskette's square plastic cover ihould enter the drive first . The edge 
of the diskette with the Ubel should enter the drive last* 



A Good 
RULE OF THUMB 

Hold a diskette with your right thumb over the label: 

that pretty much insures the correct orientation 

when you put the diskette in the drive. 
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Inserting a Diskette 

Tush the diskette gently until the diskette is entirely into the drive- 
Do not bend the diskettel If it is pushed in too hard, the diskette can 
be permanently damaged. Close the drive door by pushing it down again. 
The two metal fingers (which can be seen inside the slot when the drive 
door is closed) should Just clear the diskette as the door close*. 

A diskette is removed by opening the drive door and pulling the diskette 
carefully out of the drive. The act of opening the disk drive door lifts 
the "head" off the disk. IE you plan to leave an unused diskette in a 
drive for several hours* it's a good idea to open the door so the head 
won't rest on the diskette. 




NEVKR remove a diskette while the drive's "IN USE" light is on. This may 
Permanently damage the diskette, and Is almost sure to destroy the 
Information on it. In such a case, the diskette can usually be re-used, 
but you won't be able to recover the lost information* 
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BACKGROUND 

Learning to use the disk and its operating system consists of learning *i 
few special Instructions, several of which are straightforward extension** 
of familiar BASIC Instructions* This manual assumes that you're familiar 
with the Apple II. and feel comfortable writing simple BASIC programs. 

To learn how to use the Apple 11 and Integer BASIC, consult the Apple II 
BASIC Programming Manual . (Apple ProdttCI ffULffflflSX). To Irarn h**w t <: j>. 
Applesoft BASIC, consult the Applesoft II BASIC Programming Reference 
Manual (Apple Product #A^!Ltf00b)* The Applesoft manual assumes you're 
already familiar with the Apple II and simple BASIC programming* If 
you're not familiar with either manual, we will wait here while you learn 
about the Apple 11, before going on to learn about DOS. 

* 
* 
* 

Throughout the manual are listings of programs that Illustrate how to use 
DOS. Host of these programs are in Applesoft; a few are in Integer BASIC. 

Sometimes the changes needed to convert an Applesoft program to Integer 
BASIC are mentioned; other times, they are not* Consult Appendix H in the 
Applesoft manual for details on the differences between programs written 
in Integer BASIC and Applesoft BASIC* 

A little bit of hands-on experience is worth a lot of reading* Once your 
disk drive is hooked up and the computer is turned on, follow each of 
these descriptions by actually trying out the procedures on your Apple II. 

Put the Apple II into BASIC — either Integer BASIC or Applesoft. Place 
the System Master diskette into the drive. The diskette should be 
labelled WA-9BB2-XX- The last two digits are indicated by X's, since It 
doesn't matter what they are. If you have more than one drive, use Drive 
1. This section of the manual only deals with one drive and assumes that 
you've followed the standard conventions, putting the controller into slot 
16. 

With the disk drive attached, and the diskette in the drive, and the disk 
drive door closed t you will find that the Apple II performs Just as it did 
without the disk* Nothing is changed* It Is as If the disk drive were 
not there* And, as far as the Apple II is concerned, the disk drive is 
not connected yet: a special command must be given to inform the computer 
that the disk, drive and the new DOS instructions are available* 
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Even though DOS commands look like BASIC commands, they do not always 
follow the same rules* For example, multiple DOS commands can not be put 
on one line, separated by commas* The SYNTAX ERROR message results* 



(KfflUlH) means you should press the key marked "RETURN". Press the RETURN 
key aftor each Instruction* 

<RKSET> means press the key marked "RESET". If you have an Autostart ROM, 
• press of the RESET key will cause the Apple to beep and display a prompt 
character. With the old ROM. a press of the RESET key will put you into 
the Huh 1 TOR program, which uses * as its prompt character. 



(RSC> means press the key marked M ESC"- 
hut nowadays has other uses. 



5C" originally meant "escape 1 



(CTRU is a bit different. It means you should press the key marked "CTRL" 
(which stands for control) and continue holding it down while you type 
another key. For example, <CTRL}C means type the "C" key while you are 
holding down the CTRL key- Sometimes use of the control key la indicated 
in another way: CTRL-C and fCTRLIC both mean the same thing. 



HOTE *** 

Characters typed while holding down the CTRL key 
do not appear on the screen. 

BOOTING DOS 

The process of adding the DOS commands to the BASIC in your Apple II la 
called booting the disk. The disk may be booted from Integer BASIC, from 
Applesoft or from the Monitor. There are various ways you can use to boot 
DOS. From Integer BASIC or Applesoft, the PR#s and IN*s commands (see 
your Applesoft manual) may be used. From the Monitor, "control commands" 

IIm?nn!* 7t R A lll*?* y it UB t d ' ° ncc you 8et D0S b00 *ed, it's all the 
same DOS. it doesn t natter how you got there* 

In the examples below, the lower-case letter & stands for the number of the 
Apple II slot in which your disk controller card is located. The standard 
location for the controller card is slot th (see Chapter I, Installing the 
Controller). After any of the following commands, you must press the 

From Integer BASIC (whose prompt character is > > 
you can use either of these commands to boot the disk: 



You type: PR 0s 
or: INPs 



Example: PR06 
Example; Ififh 



From Applesoft (whose prompt character ts 1 > 

ynu can use either of these commands to boot the disk: 



You type: PR#s 
or: IN J* 



Example: PR 06 
Example: IN #6 



gr: i| 



From the Monitor (whose prompt character Is * ) p 
you can use either of these commands to boot the disk: 



SPECIAL KEYS 

Sonetlmea thiE manual uses the curly brackets { and ) to enclose the 
names of special keys which you are supposed to press on the Apple 11 

keyboard. 
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ST * 

»r-si 



You type: CsflflC 

or: s(CTRL}P 



Example: C600C 
Example: 6{CTRL)P 
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In the rest of this Manual, when you are to re-start the DOS In this manner 

we will simply say: "boot the DOS" or "boot the disk". Both expressions 
(very popular among computer users) mean the same thing. "Boot" is short 
for the word ,r bootstrap" and the term is from the expression "to pull 
oneself up by one's bootstraps". In any case, it does not mean to kick the 
disk, even if you do feel In such a mood from tiae to time* 

Now try booting DOS from your System Haster diskette. Start by puttlnt 
your Apple II in BASIC — either Integer BASIC or Applesoft will do. 

sure the diskette Is properly inserted. Next type 

PR#6 

and press the RETURN key as usual. From now on, it will be assumed that 

you will press the RETURN key after each instruction. 

Once you press the RETURN key, the red "IN USE" light will come on, the 
disk will make whirring and clacking noises <don't be alarmed — it's not 
getting ready to fly away) and in less than 10 seconds, a message will 
appear. The message should be similar to the following: 



± 









*|3 

± 



If you now try to use BASIC, you will find that most commands still operate 
normally and, aside from the message suddenly appearing, the Apple II seems 
unchanged. What has happened Is this: a few new commands have been 
introduced, and a few old ones have new capabilities. Two changes have been 
made that are not obvious, however: 

1) The HIMEM pointer to the highest memory location you may use 
has been reset to accomodate the DOS 

2) Your Apple II may have lost some of 



n 



graphics capabilities, depending on the amount 
in your computer* 



program. 

its high-resolution 
memory 



of 




«^ 



** Versions of DOS that use 13 sectors can't be booted when the system 
expects 16 sector diskettes. (The diskette spins and hiccups, but nothing 

comes out.) To run a 13 sector diskette, update it to 16 sectors with the 
MUFFIN program. You can also use the BASICS diskette to boot 13 sector 

diskettes on your sixteen sector system. See Appendix I to learn how- 

IF BOOTING DOESNT WORK 

If you can't successfully boot your System Master diskette, re-read the 
manual carefully — that cures 9U of all problems. 

This isn't likely, but if your unit was shipped in a Sherman tank or some 

such, the connectors inside the disk drive may have worked a bit loose. If 
you are at all squeamish about handling the insides of your drive, your 
dealer will be glad to check it out. 

If you enjoy getting your fingers into the works, you can turn the computer 
off, and disconnect the drive from the controller. Loosening the four 

screws on the bottom of the drive allows the mechanism to slip forward out 
of the case. Tighten the connectors by pushing them gently onto the 
circuit boards* 



IT* 

IT q 
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?■* .i ■-■«.-? M i the unit and It will probably now work* If this first aid 
doesn't work, see your dealer. Don't make any adjustments. 

INITIALIZING NEW DISKETTES 

The System Master that comes with this manual is a very special diskette: 

It contains programs that allow you to copy an entire diskette, update any 
diskette that has an earlier version of DOS, and more. Programs that 

demon*, t rate various capabilities of DOS are also included on the diskette 
and discussed in the manual* 

Take the System Haster diskette from the drive, and replace it with the 

other blank diskette supplied with your drive* How try an experiment. 

Get BASIC going, then type 
PR 06 

and watch what happens* The red IN USE light cones on, and the disk drive 

makes a few clackety noises, then it Just keeps whirring softly and quietly 
and It doesn't stop. You'll have to press the RESET key to stop it 

(normally, this is a BAD idea, but these circumstances aren't normal). It's 
a good idea to open the disk drive door before pressing the RESET key, since 
that lifts the head of the disk drive off the surface of the diskette. 

What happened was this: your Apple II went on a fruitless unending search 
for Information on a blank diskette (on a clear disk you can seek 
forever.--). When a new diskette is manufactured. It contains no 
information at all, like a blank tape purchased for a tape recorder. To 
operate in the computer, there must be special Information placed on the 

diskette: the diskette must be initialized. 

If you've been keeping up with the hands-on part of the example, your blank 
diskette is in the drive and you just pressed the RESET key. Now take out 

the blank diskette, replace it by the System Master diskette, and close 

the door of the drive- Get the computer into BASIC and type 

PR #6 

again. You should again get the message you got before when you booted* 

Once more the DOS commands have been added Co BASIC* 

The INIT command can be used to IHITialize a "slave" diskette* Slave 

diskettes are memory-size dependent: the size of the system which 

initializes the diskette determines the size of the system which can use 

the diskette- If a slave diskette Is created on a 32K system, then it can 
only be used on a system with 32K or more memory* On larger systems, only 

32K of memory will be used. After INITializing a slave diskette, you can 
use the MASTER CREATE program (see Chapter 5) to tranform your slave 
diskette into a "master" diskette whose DOS is self-relocating so that 
memory is used efficiently. The HIJFFIN program will allow you to transfer 

the contents of your 13 sector diskettes to 16 sector diskettes. 

The INIT command requires the use of a BASIC program called the "greeting" 
program since it greets you: each time you boot the diskette the program 
will be run automatically* The greeting program is commonly named "HELLO" 
hut you could call it "BONJOUR" or "BUENOS DIAS" or whatever you like. It 
helps keep life simple to use a standard name for greeting programs as you 
INITiallze diskette*. 
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Here's a atep-by-step guide to INITlallxlng a slave diskette. We assume 
DOS Is already booted as described above* 

1) Rnove the System Master from your disk drive and replace It with 
a blank diskette. 

2) Type NEW. then type a greeting program. Here Is a simple sample of a 
greeting program: 

... . ■ - 

- 

- ■ 

You should supply your own name, system size, the current 
date and other Information to help you quickly and easily 

determine the diskette's history and slave/master status* 
You may RUN the program to see If It does what you expect- 

3) Once the program Is satisfactory, type this Instruction: 

IN IT HELLO 

When you press the RETURN hey, the diskette will spin for nearly 

a minute, making clacks and little whispery noises every 
now and then* The appropriate prompt character (e.g., ] for 

Applesoft) will be displayed when INITlaliiation Is complete. 

4) Mien the disk quiets down and the IN USE light goes off* 

remove the diskette and label it* The label should say 

something like 

32K SLAVF DISKETTE CREATED 8 AUGUST 1980 

so that Just by looking at it you know it isn't blank. 

Put aside the System Master diskette supplied by Apple Computer* Put it 

where it won't be damaged by heat, physical stress (kids? dogs?) or 

magnetic objects. And where It won't get lost. It should be treated 
especially carefully, since it contains many useful programs. 

Once a diskette has been INITiallzed, it will be referred to as s slave 
diskette. To label your slave diskette, you had to take it out of the 
drive- Put it back in and try hooting It: the message In your PRINT 
statements should appear* If you followed the model given above* the 
screen should say: 

Since the once-blank diskette now can boot* you know that it has been 
INITiallzed correctly. From this point on you will use the newly 
INlTlalited slave diskette for experimentation. You cannot do some of the 
procedures to be demonstrated below on the System Master, because the 
diskette is "write protected", as discussed in Chapter 4- 

If you have purchased additional blank diskettes, it would be a good idea 
to INlTialire a few of them now* 






It a 
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LOAD-ING AND SAVE-MG WITH DOS 

Bom the Jtyutea with your Initialized diskette* Type 
NEW 

to make sure no programs arc in memory. This will erase your greeting 
program) (which is LOADed and RUN when you boot DOS) fro* memory (but not 
from the diskette). 

Now type thin tiimple program: 



ft Mr.n C-tfLWT PROGRAM 
IB FG» I - 1 t() 10 
3ti PRINT i, 
iO KEX7 t 
4* ENf 



RUN It once or twice to make sure that it works as you expect 
Applesoft, when the program is RUN you'll see this: 



In 



1 

4 

T 



s 

5 

a 



reference purposes, call this program ONE TO TEN, since it counts from 
to ten. To store this program on the diskette, type the instruction 



For 
one 
SAVE ONE TO TEN 

When you complete the coomand by pressing the RETURN key t the disk will 
whirr for a few seconds, and the program will be saved. 

If you had typed 

SAVK 

without any name, the program would have been saved 

usual (assuming you had operated the tape recorder i 

BASIC Programming Manual), 



on cassette 
s described 



tape, i 
in the 



To prove that 

First, type 

LIST 

then 

RUN 

to see the program is still 

demonstrates that using DOS 

the program in any way. 



the program has been SAVEd on diskette, do the following. 



In 
to 



memory 
SAVE a 



and still operates properly. This 
program on a diskette doesn't affect 



type 



Nuw 

NEW 

then 

LIST 

There will be no program left at all — it disappeared when you typed NEW. 
To really make sure the program is dead, turn off the computer. You can 
even take the diskette out and put it (gently) back in again. Turn the 
computer hack on again, get into BASIC and boot the DOB. Type NEW (which 
program), and then LIST. Nothing there? Right. 



craues the WIW 
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Now type 

LOAD ONE TO TEN 

and the disk vill vhlrr for about two seconds. LIST th* program: It la 

revived* RUN it, and you will find it in perfect health- That Is all there 
is to SAVEing and LOADing programs frow disk: it's Just like using the 
cassette tape except that a file name is used, and It's faster* 

CATALOG 

You stored the program ONE TO TEH on your diskette. Actually, you had 
already stored another prograta- To see what programs are stored on a 

given disk, type the command 
CATALOG 

and a list of all the programs on the diskette vill appear* night now your 
diskette's catalog should look like this, if your programs were written in 

Integer BASIC: 
I MZ HELLO 

HKnxnm 

The letter "I" In the left column means that the programs are In Integer 
BASIC; before names of Applesoft programs you'll see an "A"* Besides BARIC 
program files* there are also other kinds of files that can be stored, and 
they will be explained in Chapters fi through 9. The numbers after the 

file-type letter represent the length of the stored program. In this 

case, 002 diskette "sectors" were required to store the program- Each 
diskette sector can store up to 256 bytes of information. The shortest 

possible file, an empty text file (see Chapter 6), requires 001 sector to 
record certain "housekeeping" information* In all, a diskette can store 
496 sectors of programs and other files* Lastly, each entry in the 
catalog contains the name of the program. See Appendix C for details on 
how Information is stored on the diskettes. 









it a 
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When a file exceeds 255 sectors, the length reported for that file by 
CATALOG starts over again at 



x 



There is no way to tell from looking at the CATALOG which program la the 
greeting program. So It helpa if you always give the sane naoe to your 
greeting program- 
Sometimes you'll have more programs on a diskette than will fit on the TV 
screen at one time* CATALOG will cause the first 18 programs to be 
listed* When you're ready to see the other programs on the diskette, 
press any key except the RESET key, CTRL key or the SHIFT keys* 



er-q 



WHATSINANAME? 



Flic MBM must he from 1 to 30 characters in length; DOS will truncate 
longer file names to 30 characters. A file name must begin with a letter, 
Any typeable character except the comma ( , ) may appear In the name- 






Here are some legal file names: 

SOHNAMBULIST1CS 

UNE TO TEN 

HIRES 34 

TUB QUALITY OF MERCY: UKSTRAIHED 

More a f<-v names that will not work 

I TO 10 

111 THERE, BABE 

INEPT EXCESS VERBIAGE DISQUALIFIES NAMES 



(and reasons why): 

(begins with a digit) 

(contains a comma) 

(will be cut to 30 characters) 



Although the name of the last fil 
displayed by CATALOG, you can, if 
entire name when LOADing or RUNning, and all 



will be cut to 30 characters when 
your fingers can take It, type the 
vill work correctly* 



Every line in the catalog represents a "file". The BASIC program you 
stored Is an example of a file. The rules given here for file names also 
apply to the names of programs. 
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If a control character is accidentally (or even purposefully) typed into i 
name, that character will not appear on the screen when you get a catalog. 

For example, if you type (CTRL)T instead of plain "T" In the name 
"AGATHA"* the catalog Hating would appear to be 
ACAHA 

However, if you tried to LOAD that file by typing 
IX>AD ACAHA 

the computer would reply 
FILE NOT POUND 

even though the name you typed seemed to be Identical to the naoe in the 
catalog. So be careful: don't inadvertently put control characters in 
file names. (Although, heh hnh. It's a clever way to keep you out of my 
bank records if all files have secret control characters embedded In 
them...) The File Names section of Appendix F contains tips on how to 
find out what control characters are imbedded in file names* 



RBiAME-INGFILfS 

For one reason or another, you'll occasionally want to change the name of 
a file. Suppose you get tired of typing the file name ONE TO TEN and 
decide to call the file COUNT. Just type 
RENAME ONE TO TEN t COUNT 

and after a moment of whirring you'll again see the BASIC prompt 

character* Now type 

CATALOG 



to verify that all went as planned* 



© 



The RENAME CGBimatid docs not check to see whether the new naoe you're 
■...., already exists or not, so it's entirely possible that you can RENAME 
until oil ill.- on a diskette have the sane name. ..a most undesirable and 
rnntufctoR situation that Is beat avoided. 
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DELETE-ING FILES 

It Is easy to remove files from the diskette- Type 

CATALOG 

again to see the two files that are on your diskette* Now type 

LOAD COUNT 

(assuming you changed the file name as shown above) to get that program 

into memory- Delete this program from the diskette by the instruction 

DELETE COUNT 

and test that your deletion has worked by typing 

CATALOG 

Pnly the greeting program — probably called HELLO — is left. Since the 
program COUNT is in memory (that's why you LOADed it), you can place it 
back onto the diskette with the familiar command 

SAVE COUNT 

Take a look at the catalog to see that the prograti is again on the 

diskette. 

If yon try to DELETE a file that's not on the diskette, you'll receive the 

FILE NOT FOUND 
message. 



RECOVERING FROM ACCIDENTAL RESETS 



(if 



Suppose you're without the DOS in either Integer BASIC or Applesoft. 
Applesoft Is in firmware* we assume the switch on the card is set for 
Applesoft)* If you accidentally strike the RESET key, you can recover with 
your program Intact by using CTRL-C. The DOS also has recovery procedures 
that will usually preserve your program and data. 

If you ore working with an old Monitor POH and have already booted DOS, and 

then press RESET, you get the Monitor ( * ) prompt. To return to DOS and 

the BASIC you left, type 

JpffC 

k member that's a zero, not the letter 0. between the tetters D and G* 

If recovery to DOS does not work, and the program still LISTS, all is not 
lost: save the program on tape (you did remember to keep your tape drive 
for just such an emergency, didn't you?). Then at your leisure you can 
boot DOS, LOAD the program from tape, and SAVE it on a diskette. 
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If you accidentally (or intentionally) hit the RESET key while the disk's 
red "IN USE" light is on, the information on your diskette may be 
clobbered. Problems are most likely to occur if this happens when you're 
putting information onto the diskette using 1 SAVE, BSAVF, or WRITE 
command. In the event that it Is clobbered, you probably won't be nble to 
recover your programs from the diskette. If nothing else works, you can 
re-initialize the diskette and use It again, 

the files on the diskette. 



but INITinlUing destroy* all 






if ; h 




I 



if =a 

IF -51 

iF"3 



i? : 3 



4, 



If your IN USE light stays on for several minutes but you don't hear the 
usual disk sounds, your system may be "hung". Pressing RESET ray be the 
only way to turn off the light so you can restart the system. 

A diskette can be partially clobbered, so that it will not boot* However, 
in such a circumstance, you can sometimes boot another diskette, then LOAD 

programs from the partially clobbered diskette and save them on an un- 
damaged diskette* Or use the FID program to copy 
programs. 



individual files or 
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tffcL. 






iCT'i 



20 




DRIVE, SLOT AND VOLUME OPTIONS 

Host DOS commands allow you to specify a number of options, such i 
disk drive you arc using, which sloe contains the disk controller 
drive, and a 'Volume number" for the disk. 



a which 
for that 



The disk drive option allows you to operate with more than one drive. 
Each controller hs8 the ability to control either one or two disk drives* 
Normally, Instructions refer to drive 1. This is the default drive 
selection: if you don't specify a drive, drive 1 will be used* If you 
wish to specify drive 2, you use the notation D2 separated from the file 
name or other disk options by a comma* For example, to Initialize a 
diskette in drive 2, you could use the instruction 
INtT HELLO, D2 



has been specified, all further disk command s 
drive I is again specified- Drive 2 is now 



1 is again specified* Drive 2 is 
the above INITialization, the command 



After drive 2 

drive 2 until 

drive* After 

CATALOG 

will list the 

I, you use the 

example, 

CATALOG, DI 

will show you the contents of the 

default drive number back to 1* 



refer to 

the default 



files stored 
notation Dl 



on the diskette in 
separated from the 



drive 2* 
file name 



To specify drive 
by a comma. For 



diskette in drive 1, and change the 



If more than two drives are in use, then additional controllers are 

required. These are placed in different slots than the first controller 

(which is customarily in slot number 6)* You can specify slot n (where n 

is a digit from 1 to 7) with the notation Sn separated from the file name 

or other disk options by a comma. For example, to initialize a diskette 

in drive 1 attached to a controller In slot 5, you would use the 

instruction 

INIT HELLO, SS, Dl 

The file name must come first, but order of the options is not Important* 

The default slot number is the one you used when booting the DOS. Once a 
different slot number has been specified, it becomes the default slot 
number until it is explicitly changed. 



$ 



After using a DOS command with a Slot parameter naming a slot that doesn't 
contain a disk controller, you get an 
I/O ERROR 

message, and all appears to be fine. But DOS now thinks the default slot 

number is the bad slot number, and that the disk that isn't connected to 

that slot is still running . Even if the next DOS command specifics the 

rifl ht slot, it vatts in limbo forever for the non-erftt4nt disk to 

stop running the last command- If you have no program In memory that you 

care to save, simply re-boot DOS. To recover with your program intact, do 

this: 

1) Reset the default slot by typing 
CATALOG, Ss 

where s is the correct slot number. 

2) When the system hangs, press the RESET key. 
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3) Type 
ID*: 
and all 



•tumid be fine again. 



s 



DOS must be hooted from a diskette in Drive 1, not Drive 2. 

The volume number option can be used to protect diskettes from being 
accidentally written over- For example, suppose your have a 
diskette-based Inventory system, where each month's records 19 on a 
different diskette with a unique volume number. Then when you go to enter 
information for the month of January, you must be sure to specify the 
correct volume number* Otherwise, the information won't be written to the 
diskette and you'll get a 
VOLUME MISMATCH 



A "volume number" may be assigned to a diskette when it is ItflTlalized, 
using the notation Vn separated from the file name or other disk options 
by a comma. For Instance, to Initialize a diskette using the name "START 
UP" for the greeting program (the program that is run each time the 
diskette is booted), where the diskette is in drive 2 of a controller In 
slot 5, assigning the diskette a volume number of 128, you would use the 
command 
INIT START UP, D2, S5, V128 



& 



The volume number of 
the diskette. 



a diskette may not be changed without re-INlTialiaing 



The drive number, slot number and volume number options may appear in any 
order. The above command is equivalent to 

INIT START UP, V12B, S5, D2 
and to 

INIT START UP, S5, V128, D2 

and so on- 



The volume number of a diskette must be an 
no volume number is specified with INIT, a 
assigned to the diskette* 



integer from 1 through 254. 
default volume number of 254 



If 

is 



£ 



The command 
IN IT HELLO, V0 

dors not give any 
number 254. 



message, but assigns the diskette the default volume 



AM DOS commands can specify the volume number, if you wish DOS to check 
that the volume number on the diskette agrees with the V option. If you 
do n ot specify any volume number, or if you specify volume zero, or if 
you type "V" without a number, DOS will Ignore the diskette's volume 
number- If you accidentally specify an incorrect volume number, the 
nyatn will reject It with the 
VOMIHK MISMATCH 
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Volume mismatch error 
case you wish to know 



head of 



cannot occur when you ask to see the CATALOG. In 
the volume number of a diskette, It Is given at the 
the CATALOG listing. 



Additional discussion of options is found where each command is 
introduced. Also, the Information is concisely summarized for each 
command In the Command Summary Appendix and on the Quick Reference Card 
accompanying this manual. The following section explains how to interpret 
these concise summaries. 



SYNTAX 

Syntax refers to the structure of a computer command, the order and 

d of the command's various parts. A simple notation is used to 
syntax of each DOS command. Items in brackets (( and 1) are 
optional parts of a DOS command may be specified in any order, 
and commas must be typed as shown; lower case letters 
you must supply. In specifying the syntax for DOS 



K 3 



describe the 
optional; 

CAPITAL letters 
stand for items 
commands. 






2. 



f stands for a file name 

d stands for drive number — either 1 or 

s stands for slot number — 1 through 7, 

v stands for volume number — I through 254, usually. 

A diskette's volume number may not be 0. Specifying a 
volume number of in a disk command is a "wild card 11 that 
tells DOS to ignore the volume number on the diskette. 
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Additional abbreviations used in 
of the Command Summary Appendix. 



this manual are summarized at the start 



Any numerical constant (the drive number, volume number, etc.) in a DOS 
command can be expressed in hexadecimal notation by preceding the hex 
digits with a dollar sign. If you don't know what hexadecimal notation 
ia. Ignore the preceding statement — you need't understand hex notation 
to understand this manual. 



INIT 
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The syntax for the 

INIT f [,W1 l.Ss] 

where the brackets 

example 

INIT HEL1.0, V17, D2 

can be interpreted as follows. 



i ■> i i command Is 

f.Ddl 

indicate options which may or 



may not be included. The 



na*e "INIT" is 



in upper case 
for file 



The command 

shown. The lower case "f" 

file name "HELLO". Next the optional 

comes a comma, then the upper case 

arbitrarily replaced by 17 for this 

Indicate chat specifying the slot number 



and oust be typed exactly as 
name is replaced by the legitimate 
volume number Is indicated: first 
for volume number was 
The brackets around ",Ss" 
is optional for the INIT command: 



'V". The 
example. 



" V " 
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In this example it's omitted so DOS will use the default slot number. The 

drive option 1* included: the comma and upper case "D" must be as shown; 
the lower case "d" Is replaced by 2 in this example. 



LOAD, RUN AND SAVE 



LOADlng, RUNning and SAVElng programs on the disk is similar to the 
corresponding operations using the cassette (except that programs are 
referenced by file name). Everything goes at least ten times faster, and 
you never need to press buttons to play, record or rewind. It is all 
automatic. There are many additional abilities that the disk brings as 
well, such as the catalog of programs and the automatic running of 
programs without user intervention. Saving data (on text files — see 
Chapter 6) is also very easy. The FID program described in Appendix J 
offers you Rome additional ways to manipulate files* 



It's a good idea to hang on to your cassette tape system for trading 
programs and as back-up storage for vital programs and data (although 
experience shows that disk storage Is even 

storage of programs and data)* 



re reliable than cassette 



If you have a program in BASIC, and you wish to call it HENRY, then the 

command 

SAVE HENRY 

will save it on the diskette- If you have more than one drive, HENRY 
normally would be saved on the drive from which you booted DOS (the default 

drive, unless you specified a different drive after booting). You can 

specify drive number, volume number and slot number as with the INIT 
command. For example, to SAVE a file called AGATHA on drive 1 of the 
controller in slot 2, where the volume number of the diskette is 214, you 

could use the command 

SAVE AGATHA, Dl , S2, V2U 

As before, the three options can be put In any order. If you had omitted 

the volume number option, AGATHA would have been saved Just the saiae, bless 

her, but DOS would not have checked that the diskette was volume 214- 

Program names are file names, and must follow the file name rules: they may 

be up to 30 characters long, and must start with a letter- They nay 

Include any characters you can type except commas or control characters. 

Here are some valid names for files: 

CHECKBOOK 

THE QUALITY OF MERCY 

HIRKS3A 

NOV: HEAR THIS1 

To LOAD a program named AGATHA, use the command 
LOAD AGATHA 

in. i the program of that name, if there is one in the catalog, will be 
loaded. To test if AGATHA is loaded, see if she can walk a straight line. 



I r you want ACATHA to RUN 
course, use the commands 
LOAD ACATHA 



after she's LOADed (poor thing) you can, of 
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then 

RUN 

But there's a way to do it to just one step: 

RUN AGATHA 

is a DOS command that first LOADs the specified file, then ftUNs it. 

Here's the syntax for the SAVE and LOAD and RUN commands: 
SAVE f (»Sal [,Dd] [.Vvl 
1.0AD f [,SsJ UN] l*Vv] 
RUN f [,Ss) [,Dd] UVv] 

Examples follow: 

SAVE OUR HAPPY HOME. Dl» 57 

LOAD UP 

RU« AMOK, S7 
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If, when you try to SAVE a proKram 



you 
error, or 



typing 
If DOS was originally booted. 



get a SYNTAX ERROR 
DOS isn't booted. 

use 



message. 
First, try 



T BOOT IT. Booting DOS 
the program on tape, using 



either you have made a 
re— typing the command* 
3D9G 

to try to recover- If DOS Un't booted — DON 

will erase aov program In memory . First, save 

the usual cassette 

SAVE 

command. Now boot DOS. Next, use the usual cassette 

LOAD 

command, to bring the program back into your APPLE II 's memory from the 

tape. Nov you will be able to SAVE it on disk. 



a diskette is bad (perhaps someone tried to staple it 
diskette is not initialized, or If there is no 



If 

or if the 

drive, or If the door is open, the message 

I/O ERROR 

(I/O stands for Input 

using DOS. Check all 

don't need to re-boot 



into a notebook), 
diskette In the 



or Output) will appear when you try to SAVE or LOAD 
the items listed, and correct the problem. You 
DOS. Try again. 



If you use the command 

LOAD HENRY 

and HENRY is not the name of a program on the diskette In the drive, then 

you get this message 

FILE NOT FOUND 

Look at the diskette's catalog to find the program's exact 

characters and spaces must be typed exactly as they appear 

name shown in the catalog. 



file name, 
in tbe file 



All 



DELETE 



To eliminate any file that you would rather not have on your diskette, the 

command 

DELETE 

can be used. The syntax is 

DELETE f t f Ssl [ f Dd] f,Vv] 



26 






± 



mljm 

■r 



For example, the command 

DELETE EXCESS, V34, D2, SI 

deletes a file named EXCESS from a diskette with volume 

placed in drive 2 of the controller in slot I- Sectors 

"s*?t free" only when a file is DELETEd- 



nuaber 34, which is 
on a diskette are 



A SCENARIO: BOOT, SAVE, RUN, CATALOG AND DELETE 

Suppose you're running Integer BASIC and the System Master diskette is in 
your disk drive. Here's a dialog &s it might appear on the screen of your 
APPLE II* The parts you type are underlined ^ although they do not appear 
that way on the TV screen. First type 

>PR#6 

to clear the screen. You'll see the following: 

fftAUtt 

DU* VULUrtt *r* 

*H MMfc MClLU 

I) W« *«>##*% 

«* ma *i*oix 

** mw ww* * ***** 

• j m& ujLt* ««* 

*#t urn WXl* «j**i*i 

•l yttv M*V 

** ws it*-* **** 

•h *r* txrvw 

** «W Erifci WHiii 

**l «h£U Ml* 

*W **M HW W£*fl 

** tw> ftW-tlN 

** «m puts* I 



PRINT 



it 



f*J» VW MM 

: W 

I 



I At this point, you would insert the 
Slave diskette you INITialized earlier 1 
Since it is not write protected* 1 
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MSK VCtAJNE 3SW 
I 962 HELLO 
I 0K2 COUNT 
I OK? [*M0 



**• NO END Eflff 

>S£L£fiS 

JftBMRMCiCtt 

>&Et£XE-e£QS 

MSK VOLUME £54 
E 8fc*; HKLLO 
I e©2 COtWT 

MOVING BETWBI LANGUAGES: FP AND INT 

Suppose you've been using Integer BASIC, and you decide to write a program 

In APPLESOFT, or to use the computer as a calculator with floating point 

numbers (numbers with decimal points)- To invoke APPLESOFT without 

clobbering DOS, type 

FP 

(that's all there Is to it) and in a few seconds APPLESOFT will be up and 

running- The FP stands for "Floating Point", of course. (If for some 

reason Applesoft isn't available — it's not in firmware or on the 

diskette that's in use ~ then the message 

LANGUAGE NOT AVAILABLE 

will be displayed-) The syntax for the command Is 

PP USs) I.Dd) 

where the optional Slot and Drive parameters allow to to specify the drive 

containing Applesoft on a diskette. 



If you've been using APPLESOFT and DOS, you can type 

INT 

(for "Integer BASIC") to return to Integer BASIC with DOS Intact. 

suntax for this command La simply 

INT 

without any parameters. You'll generate a 

SYNTAX ERROR 

message If you try to use the D or S parameters with INT. 



The 



x 



If you type 

INT 

while In Intel 

If you type 

FP 

while in Applesoft , you'll lose any program In memory. 



ilC , you will lose any program in memory- Similarly, 



When you switch from Integer BASIC to Applesoft or vice versa, you'll lose 
any program you happen to have In memory* 






3! 



9" 






s 



3£ * 
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In addition lo moving back and forth between the Apple's BASICa, you say 
wluli to enter the Monitor and be able to use DOS coaunda. To do so from 
either Applesoft or Integer BASIC, type 
CAI.I. -IM 

mid yon should get the Monitor prompt character, * . To return to 
whichever BASIC you started from with your program and DOS intact, type 
Hi*: 



X 



Pram the Monitor, you nay also type 

INT 

to return to Integer BASIC, or 



to return to Applesoft; In either case, DOS will still work but any 
pr ogram In memory will have disappeared . 



x 



If you get n 

PROGRAM TOO LARGE 

message when trying to execute an 

PP 

command, type 

INI 4 

first, to reset the system. Then type 

PP 
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Even though your diskette contains the Integer BASIC program named 
APPLESOFT, do not type 

RUT* APPLESOFT " 

If you do, Applesoft will seem to be running fine until you press RESET, 
say, and try to re-enter Applesoft. Then, since the DOS thinks you are in 
Integer BASIC (because APPLESOFT was an Integer BASIC program), you will 
be in trouble* 

To move the APPLESOFT program from one diskette to another, simply 

WAD APPLESOFT 

from whatever diskette it's on, then place the diskette you wish to 

contain Applesoft In the drive and type 

SAVE APPLESOFT 



USE Of DOS FROM WITHIN A PROGRAM 

Very often it's useful to be able to execute a DOS command from within a 
BASIC program. For example, you may wish your greeting program on a disk 
to print out the contents of the disk by doing a CATALOG command. Kany 
DOB commanda can be executed from Inside a BASIC program. This is done by 
PKINTing a string that consists of a CTRL-D followed by the command. 

Here la an Applesoft program that, if used as a greeting program, will 
rsuse ihe information In the PRINT statements in lines 20 and 19 to appear 
on Mi* srrren, followed by a list of Mien In the CATALOG. 



2V 



3 RE» QftEETlrJG F*OGR*H 

IB D# - CHR* C*>; REM CHKJ- 

IS CTRL^P 
29 PRINT "SLffVE DISKETTE CRESTED 

3» PRJNT -BV flMV VOfr N B «W3U 

40 PRINT D»- "C«TflLO(P 
9 END 



In Applesoft is Illustrated In the above 
consisting only of a CTRL-D t is created 
first line of the program. Later it can be 



The recommended way to do this 

program. First the string D$, 

using the CHR$ function in the 

used as in line 40 

40 PRINT D$; "CATALOG" 

Note the semi-colon after the 05 and the quotation marks around the DOS 

command. The semi-colon is optional in Applesoft PRINT statements* so if 

a program has many DOS commands in PRINT statements, you may find it saves 

typing time and memory space to simply omit them* and use the form 

40 PRINT D$"CATAL0G" 

In Applesoft v you can use the CHRS function to specify CTRL-D 

10 D$"CHR$(4): REH CTRL-D 

But you need to recall that the ASCII code for CTRL-D is 4, so a RBHark 

may be useful. (The CHRS function is not available in Integer BASIC.) 

In either Integer BASIC or Applesoft you may define CTRL-D by 

typing the characters 

DS-" 

then typing the letter D while holding dovn the CTRL key, and then typing 

the quotation mark* ". Note that the CTRL-D does not print on your 

TV screen. The final command will appear as 

DS- IW 

Since control characters do not print, it's often a good idea to follow 

with a REMark to remind you of what actually is in the string. Here's the 

above program written in Integer BASIC: 

16 D#="* KEH THERE 15 flf- IM I 9L 

E CTRL-t> BETWEEN THE OUOTES 
2* PRIWT "SLrtVE DISKETTE CflEftfED Of* 

yZK 5VSTEH* 
3» PRINT "BV flHV DOM'S ON & flUQUST 

4» PRINT [>*j *C«THLOG" 
5« END 

Only one DOS command may be used in a PRINT statement. The PRINT 
statement must begin with the CTRL-D and end with the DOS command. 



* 

m ^ 

at =a 

» =1 



■trq 
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Using the right-arrow to copy a BASIC statement containing an invisible 
control character will erase the control character? 
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In DOS commands executed by a program* the DS must be preceded by a RETURN 
or it will be Ignored. RUNntng this program 



*> M M TESTCOTPLOG FR00RW1 

fM-^ FEM THERE IS *W IHV 
I516I-F CTRL-D BETWEEN THE *KJ 
OTES 
20 RftfNT -TEST', 
30 PRINT £■*; 'CATALOG" 

46 ew> 



will cause 

TESTCATALOG 

to be displayed, since the semi-colon suppresses the RETURN at the end of 

the PRINT command in line 20. To correct this, and cause the DOS command 

CATALOG to be executed when the program is RUN, just delete the semi-colon 

(;) from the end of line 2ft. 

These DOS commands should only be used within programs in a PRINT 
statement beginning with a CTRL-D: 

OPEN 

APPEND 

READ 

WRITE 

POSITION 

These DOS commands may be used in Immediate-execution mode, and also from 
within a program using a PRINT command with CTRL-D: 

CATALOG BSAVE 

SAVE BLOAD 

LOAD BB™ 

RUN EXEC 

DELETE CLOSE 

RENAME CHAIN 

LOCK and UNLOCK PR* 

HON and NQHON «*# 



The DOS command MAXFTLES may be used as desct ibed above in an Applesoft 
program, but It must be used in a special way from an Integer BASIC 
program, as discussed in the section about the EXEC command in Chapter 7 



The DOS command INIT should be used only in tmmediate-sxecution mode 
(dire consequences may result If you ignore this admonition)* 
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CHAPTER 4 



SAFE 



CTMtiRg a T»nslt«y ByttMt 

LOCK ifcd tftfUK* 

f*M«a«ts« Yoanwlf «««ift»t Duutw 
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Two ways of protecting you and /or your diskettes against disaster have 
already been mentioned. Chapter 3 mentions using the Volume option to 
ensure that you place information on the desired diskette. The use of 
control characters in file names can also be used as a way of protecting 
yourself (so* Chapter 2, "What's in a Name?" and also Appendix F, "File 
Names"). If what appears in the CATALOG as 
MY BANK ACCOUNT 

In fact has your initials placed as control characters at some point(s) in 
the name, then it's unlikely that anyone else can access the file. 



This chapter mentions a variety of ways of protecting you and your 
diskettes against various undesirable events* You'll probably find one 
more of tha techniques useful at one time or another. Firat, consider 
making a special purpose "turnkey" system. 



CREATING A TURNKEY SYSTEM 



OX 



i doctor wants to do the office accounting on an APPLE II. 
the office staff should be able to simply turn on the APPLE II, 



Suppose j 

Ideally. 

type 

(BESET) 6(CTRL>P {RETURN) 

and immediately be in the midst of the doctor's accounting program. Since 

the accounting program would (hopefully) communicate with the user in 

ordinary English, the staff wouldn't need to knov BASIC or anything else 

about the APPLE II. The computer would become an accounting system, its 

internal characteristics unimportant since all the staff needs to know is 

how to use the accounting program. 

This is the essence of a "turnkey" aystem: from the user's point of view 
the computer is a device that does only a particular task, and getting the 
system started Is as simple as turning a key in a lock. In this case, the 
"key" is simply turning on the Apple's power switch and pressing five keys 
on the keyboard. It does not require computer expertise to be able to do 
that. 

You can use the diskette's "greeting program," named when you INITialized 
the diskette, to turn your APPLE II into a turnkey system. Let's say that 
you wanted the computer to run the COLOR DEMO program (provided on the 
System Master diskette) every time you booted Disk II. Here's howt 

1) lNlTislize a blank diskette, as described in Chapter 2. 

2) place the System Master diskette in your drive and type 
RUN COLOR DEMO 

Once you're satisfied that the program RUNs correctly, type 

{CTRDC 

to stop the program and return to BASIC. 

3) Put your newly initialized diskette into your drive. We'll 
flSHuoo that you called your "greeting" program HELLO when 
you initialized the diskette. 

4) The program COLOR DEMO Is now in memory. Vhen you type 
SAVE HELLO 

DOS will erase your original greeting program named 
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HELLO nnd save the COLOR DEMO program under the HELLO 
file name* The COLOR DEMO program is now the greeting 
program on your diskette. 

To check that all works as expected, boot the disk. 

You should get the same program that you used in step 2) > 



You've just created a turnkey system: whenever that diskette is booted. It 
will automatically LOAD the COLOR DEMO progran and RUN it. 



LOCK AND UNLOCK 

Sometimes you'll want to prevent a particular program from accidentally 
being erased from a diskette: the LOCK command will do this for you. 

Example: 
LOCK NESS, D2 

Tlie CATALOG of this diskette's contents will now show an asterisk < * ) 
ne*t to the entry for HESS. 

If you decide you no longer wish to keep the file LOCKed, the UNLOCK 
command will (surprise!) unlock the file* 

Example: 

UNLOCK NESS 

The syntax for the commands is 

LOCK f [,S>] I.DdJ [,Vvl 
UNLOCK f [,Ss] (,Dd] [,WJ 

The interpretation of the notation is discussed In the Syntax section of 
Chapter 3- 

If you try to DELETE or RENAME a file that's LOCKed you'll receive the 

message 

FILE LOCKED 

You'll also see this message if you try to SAVE a file using the name of 

LOCKed file (if the file you're trying to SAVE is In the same language ai 

the LOCKed file)- 
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If you try to SAVE a file using the name of 
language, then you'll receive the message 
FILE TYPE MISMATCH 
Try again, ualng a different file name* 



VERIFY 



a LOCKed file in a different 



Occasionally Information may not be recorded correctly on a diskette* 
This may happen if the diskette is scratched or dirty, for example. The 
VERIFY command reports a file which nay be damaged or written incorrectly* 
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The syntax is the usual one for DOS commands: 

VERIFY f (,Ss) (,DdJ |,Vv] 

Examples of the way to use the command follow: 

VERIFY SAM 

VERIFY FINANCR-8 t D2,V22 



VERIFY checks to sec 
self -consistent. If 



that information In the specified file Is 

It ls> you see no message: the prompt character for 

the language you're using Is simply printed: 

> for Integer BASIC 

) for Applesoft 

* for the Monitor. 

However, VERIFY doesn't check to see whether or not a program is 

clobbered. If you SAVEd a program that was messed up somehow* it will 

still be messed up on the diskette, and it will still VERIFY- 



If the VERIFY command finds an error, the 

I/O ERROR 

message is displayed- 

If you try to VERIFY a file that isn't on the disk, the message 
FILE NOT FOUHD 
is presented. 

You can use VERIFY from Integer BASIC, Applesoft, or the Monitor, From 
these languages you may VERIFY any type of file, including text files (see 
Chapters 6, 7 and 8) and machine language programs (see Chapter 9>- 



± 
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WRITE-PROTECTING A DISK 



protect a particular file* But sometimes 
ill files on a certain diskette are not 

"write-protect" a diskette. 
In the side 



The LOCK command allows you to 

you will want to be sure that 

accidentally written over, and thus lost. To 

you merely need to cover up the squarish write-protect cutout 

of the disk. Stick-on adhesive labels are supplied for this purpose when 

you purchase diskettes but, in a pinch, any piece of sturdy tape will do. 

Note that the System Master diskette does not have a wrtte-protect cutout: 

it is permanently wrl te-protected» 



vTltc-protett tutowt 
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It you deride you want to re-use a wrlte-protected diskette, simply remove 
the label (often railed a "tab") that covers the write-protect cutout. 

Some programs cannot be used with a write-protected diskette- An example 

of such a program Is ANIMALS, one of the demonstration programs of the 

System HfiMer disk- Put your System Master in your drive, and boot DOS if 

you need to. Now type 

LOAD ANIMALS 

which will put the program into memory. Now type 

run 

and the message 

WRITE PROTECTED 

STOPPED AT 1040 

will be displayed- ANIMALS won't RUN on a write-protected diskette 

because it saves information on the diskette each tine you play the game. 

When you RUN the program, the diskette in the drive must not be 

write-protected, else the information can't be written on the diskette. 

Now ANIMALS is in memory, but you can't RUN It with the System Master 

diskette. Put an initialized diskette, one that Is not wrlte-protected , 

In the drive. Next type 

RUN 

and now you can play ANIMALS, a game that will "remember" what you "teach" 

it by saving the information on the diskette. When you're through 

playing, type 

SAVE ANIMALS 

so that you'll have the game on a diskette that's not write-protected* 

If you type 

CATALOG 

you should see that you have not only a copy of ANIMALS on the diskette, 

but also a new file called ANIMALSFILE that was created by the program 

ANIMALS. 



PROTECTING YOURSELF AGAINST DISASTER 

Floppy disks are sturdy and reliable compared to some other ways of 
storing computer programs — for example, on the backs of old envelopes* 
But It's still possible to lose or destroy all information on a diskette. 
A diskette may get scratched or damaged by heat; it may get lost, or a dog 
may chew it; someone may decide to use It as a frisbee at the beach; if a 
diskette isn't write-protected. It may accidentally get written over. And 
I diskette will eventually wear out — a lifetime of 40 working hours is 
about average. 

** Moral ** 

Keep more than one copy of a program around if you don't want to lose it* 
In computerese, "back up" any valuable program* 

If you are in the midst of writing or modifying a program, one way to back 
up the program j s to keep copies of earlier versions. Then if the current 
Version in lost you can fall back to the next-most-recent version, and 
hopefully not lose too much programming time* One good way to do this is 
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to end each til* name with a number which changes from version to version. 
For example, suppose you start to write a program called FINANCE. The 
first time you save the program, call it FINAHCE-1. Next time you work on 
the program, nave It under the name FINAtfCE-2; the third tine. It be cotes 
FINAWCK- 3, and so on- You'll wind up with a whole collection of FINANCE 
programs, with the largest version number representing the most recent 
version of the program- 
It's a good idea to SAVE a developing program periodically (with a new 

version number). If you do this every 15 or 20 minutes, an unexpected 
power failure or other disaster will not erase all your work. You can, of 
course, immediately continue working after SAVEing the current state of the 

program " just be sure to assign a new version number for the next SAVE. 
If the diskette starts filling up, DELETE some of the earlier versions* 
But it's a good idea to keep several versions around. In case something 

calamitous happens to the current version- Or you may Just happen to want 
an earlier version — not oil revisions are improvements* 

The phrase "backing up" is also used to describe keeping multiple copies of 
programs on separate diskettes- There are two approaches to backing up in 
this fashion. The first method, using one disk drive, is to simply SAVE 
the program on one diskette, remove that diskette from the drive, insert 
another diskette and SAVE the program again. 

The second approach involves duplicating all the information from one 

diskette onto a second diskette* Details of the second approach are 
discussed in the next section- 

USING THE COPY PROGRAM 

You can use the CHpY program, on the System Master diskette, to copy the 
entire contents of your current programming diskette onto your back-up 
diskette. If you are using DOS from Applesoft Basic, COPYA is the program 
to use for copying a diskette. 

In these copying programs, the diskette from which copying is done is 

called the "original" diskette. The entire contents of the original 
diskette will be copied onto a "duplicate" diskette- The duplicate 

diskette does not have to be INTTlatized before being copied onto- In 

fact, any previous information that was on the duplicate diskette will be 

erased* 

Before copying the original diskette, it's a good idea to vrlte-proteet 
It* Then you can't accidentally erase its contents, even if you put it 
Into the wrong drive* 

As default values, the program initially assumes that the original diskette 

will be placed in the currently selected drive (the drive from which you 
ran COPY or COPYA) connected to the controller card in the currently 
selected slot. The duplicate diskette is assumed to be in the other drive 

connected to the same controller card (even if there isn't another drive 
there). To use any of these default slot or drive numbers, just press the 
RETURN key when the default nunber is shown* If any of the default number** 
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are wrong, either for the original or for the duplicate diskette, you must 
type the correct nunfcer when you see that default number on the screen. 
Here's an example of using the COPY program on an Apple with one disk 
drive* It assumes your disk drive Is attached to a disk controller 
card in the same slot as the one from which you ran COPY* 



1) Place the System Master diskette in the currently selected drive. 
Type 
RUN COPY 
(RUN COPYA from Applesoft) and after the usual whirring you ahould see 

r*PL£ DlSKFnt DUPLICATION fP0Qfi*W1 



ORIGINAL SLOT. CtFHULT * 6 



2) To use the program's default slot number, slot 16 in this example, 
just press the RETURN key* 



3) When the message 



C*1V£ &EF**,"LT * 1 



appears, press RETURN* 

4) Pre^s RETURN again when you sec 

taJPLICRTC SUIT" DtPrtULt m 

5) When you see the default drive number for the duplicate diskette: 

&*!«; OBFWLT * ■ 
type 1* 

6) The message 

— WES> P€Tt*PN' WV TO BEGIN CGPV -- 



7) 



will appear. This is your signal to remove the System Master diskette 
from the drive and insert the original diskette, from which you wish 
to copy* (Did you remember to write-protect your original?) 

Now the program will proceed, first by directing you to insert your 
original diskette, then by lnforaing you that it is reading information 

from the original diskette* Then the program will let you know when it 
is ready for you to replace the original diskette with the duplicate 
diskette in the drive, and when it is formatting (INITializing) that 

diskette* After the duplicate diskette is INlTiali*ed you will be 
instructed to re-insert the original diskette so that the program can 
read some mare information from it, and then to re-insert the duplicate 
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diskette bo that tin? Information con be copied onto it. These two steps 
will have to be repeated until the entire original has been copied. 

H( When copying is complete you'll see the message 



■» = 



If yoti type Y (yes) t the copying procedure will be repeated, 
the sun* locatlon(s) for the original and duplicate diskettes 
to re-Insert the original diskette when you 



it: 1 : 11/ 
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HfESS RETURN' KEY TO BEGIN COPV — 

and that you use another diskette (either a blank or one with unwanted 
information on it) as the duplicate. If don't wish to make another 
*°py» type K* You will leave the program and DOS will assume your 
default disk drive to be the one which was the location of the duplicate 
diskette. 



If you have core than one drive* specify the slot and drive numbers for 
the original and duplicate diskettes and insert the diskettes in these 
locations before the copying oegins. Note: If you have more than one disk 

drive, the system won't prompt you to remove and replace diskettes* tt 

only does that for single drive copying. 
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If you try to copy onto a write-protected diskette you'll see the message 

1/0 ERROR 

STOPPED AT (you'll see a line number here) 

Until the write-protect label ia removed from the duplicate diskette no 
Information can bo put onto the diskette. 
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An I/O ERROR or UNABLE TO READ message will also appear when the drive 
door Is open or If there la no diskette In the drive* These messages may 
also indicate a problem with the diskette in the drive. Re aware that the 
default drive nuntoer My have been changed after you have gotten one of 
these messages* Vhen you RUN the copy program again* you may have to 
specify the drive location of the System Master diskette. 
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DEBUGGING: MON AND NOMON 

The process of trying to get a program to run the way you want it to is 
called "debugging;" program error* are often referred to as "bugs"* All 
disk commands and all information lent between the computer and the disk 
are normally not displayed on the screen* But when you're debugging, 

monitoring this information can help you track down problems. 

The HON command allows you to MONitor a variety of information. To turn 
various parts of the display off again, use the NOMON (NO HONltor) command. 

Three different parameters that may be used in these commands: 

C stands for Commands to the disk (such as OPEN, READ, etc) 

I stands for Input from the disk (when READlog a file) 
stands for Output to the disk (when WRITEing a file)* 

These parameters are used only with the NOMON snd MON commands. 

NOMON C,I,0 Is in effect: no monitoring is taking place. 



Uaually 



The syntax for che commands is 

MON (CI M] |,0| 
NOMON [CI (,IJ [,0) 

At least one of the three parameters must be present with the NOMON snd MON 
commands, else the command will be Ignored. The parameters may appear in 
any order and, as usual, mutt be separated by comas. 

There are 7 different ways in which the MON command may be used: 

command what it monitors 

MON C Commands to the disk 

HON 1 Input from the disk 

MON Output to the disk 

MON 1,0 Input from and Output 

MON C,I Cofnoands to and Input 

HON C,0 Commands to 

MON C,I»0 Commands to. 



to the diak 
from the disk 
and Output to the disk 
Input from, and Output to the disk 



*« NOTE *** 

A MON command remains In effect until a 

NOMON, INT, or FP (firmware only) command is encountered 

or 
until you boot the system 

or 
do a restart (3D0G)> 
or 
RESET 

A neat trick: you can issue a MON command and later cancel it without 

affecting the screen format — even the NOMON doea not show on the screen. 

Suppose you execute a MON command, say 

MON ''.:,■- 

To cancel the command without having it print on the screen, include 

PRINT DS; "NOMON C,1,0": VTAR PEQC(37): CALL -868 

where D$, as usual, contains CTRL-D* 
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MAXFILES 



DOS allows up to 16 files to be active (in use) at one time. DOS deals wlrh 
several types of files in addition to the BASIC program file** discussed so 

sequential text files. Chapter 8 for 



far. See Chapter 6 for 
random-access t*xt file 

binary (machine language) files. 



a discussion of 

, and Chapter 9 for the DOS c 



nds used with 



The HAXF1 LES command specifies how many active files are permitted. When 
you boot DOS, the command 

MAXFILES 3 

ia executed, which sets up the default condition; a maximum of 3 files may 

be active simultaneously until another MAXFILES command Is executed. 

The command's syntax 1b 

MAXFILES n 

where n must be an integer from 1 to 16. Specifying a value outside this 

range will cauae a SYNTAX ERROR message from either Applesoft or Integer 

BASIC; from the Monitor, a beep Is the only indication that you've done 

something wrong- 

For each file specif led, MAXFILES sets aside 595 bytes of memory space called 
a file buffer. This additional memory space for each active file la used to 
help adjust for the fact that memory speed is far faster than disk access 
speed, *ich involves mechanical motion — the disk head has to search the 



diskette. So in the name of efficiency* a 
information going to and from a diskette. 



file buffer is used to "buffer* 



If you retrieve information from a diskette, DOS brings in 256 characters at 
a time and puts them in the "Input" part of the file buffer, then delivers to 
you whatever subset of those 256 characters your program requested. If you 
are sending information to a diskette, characters are stored in the "output" 
part of the file buffer until 256 character* hove accumulated, then they're 
shipped to the diskette all at once. 

Suppose you have MAXFILES 1 and one file is active* An attempt to perform a 
DOS command (such as CATALOG) will cause the message 
NO BUFFERS AVAILABLE 
to be displayed. 

When the system is booted, the nusfcer of active files (n) defaults to 3, so 

1785 bytes of memory are reserved for 3 file buffers. Under most 

circumstances, you won't need core than 3 active files. If more files are 

required, type 

MAXFILES n 

(where n is the number of needed files) in immediate execution mode before 

loading and running a program. 



3> 



In Immediate execution mode, chanRinfc MAXFILES erases Integer BASIC 

programs and Increasing MAXFILES messes up Applesoft strings, since HIMKM: 

Is moved dewn without raoving the program or strincs. To avoid the problem, 
ri?oet MAXFILES before loading and running a program* 
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1c changes memory pointers, and n 



If MAXFILES is used within a program, 

GOTO, OOSUB, or other instruction can get lost* If you must change 
MAXFIMCS from within an Applesoft programs, make the MAXFILES command the 

first statement In the program* before any string variables arc declared* 

For example, 10 PRINT CHH$(4); "MAXFILES 5" : : 

To use HAXFILES from within an Integer BASIC program, you need to create an 
EXEC file, as discussed at the end of Chapter 6- 

TRACE 

The Applesoft TRACE command Is a useful debugging tool- But when TRACE is in 
effect, DOS commands inside Applesoft programs don't work because TRACE 
prints the line number before the D05 command- There's a partial solution 
to the problem. You can insert o RETURN (that is, CHR$(13)) in the D$ 

string 10 D$-CHR$<I3)+CHR$<4} 

and then most DOS commands will wort properly even if TRACE is in effect — 

see the exception below* 



s 



If TRACE is in effect and DOS tries to READ an INPUT from the diskette, your 
program will instead stop and wait for INPUT from the keyboard, which limits 
the usefulness of TRACE in connection with DOS* 

USING THE MASTER CREATE PROGRAM 

As discussed in Chapter 2, INIT Is used to create slave diskettes- In this 
section you'll learn how to create master diskettes. The distinction 
between a slave and a master is not readily apparent: both come charmingly 
attired in the latest in black plastic (no, not leather) garb- It's up to 
you to revise your greeting program and diskette label to remind yourself 

which is slave and which is master. 

The System Master diskette contains a program called MASTER CREATE that can 
run on an Apple II with at least 16K of memory. The MASTER CREATE program 
does the following for you: 

* Concerts a slave diskette (whose DOS la memory-size dependent) 

into a master diskette (whose DOS Is self-relocating so that 
memory is used efficiently on any size system). 

* Gives the converted diskette a new greeting program: name, the name 
DOS will attempt to RUN each time the diskette is booted. 

The MASTER CREATE program must be used with a diskette that has already 
been INlTialitcd- It will not work with a diskette that is write- 
protected* 
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Here's an example of how to upgrade the diskette INITlalized in Chapter 2 
(the one with the ONE TO TEN program on it) to convert the slave diskette 
created by INIT into a master diskette. For convenience, that diskette 

will be referred to as diskette ONE in the discussion that follows. 



Befo re using MASTER CREATE 
I) 



do the following: 



Insert the diskette you wish to convert — diskette ONE for this 
example into the disk drlve t and RUN the diskette's greeting 

program — named HELLO on diskette ONE. The message displayed by 
a greeting program should include the version of !>0S used to 
Initialize the diskette, and its status as slave or master* 



2) Change the appropriate Unas of the greeting program to display the 
new Information. "HASTIER DISKETTE", Then SAVE this new version of 
the greeting program. If the diskette's outside label requires a 
similar change, make that change now. 



3) 



Note the name of the greeting program. If you wish the converted 
diskette to RUN this same program each time it is booted, Just as it 
did before converting, you will give this greeting program name to the 
MASTER CREATE program, later on- if you've always wished your 
greeting program had some 
the greeting program new. 
MASTER CREATE program. 



other name than its present one, RENAME 
Later, you will give the new name to the 



To use MASTER CREATE, do the following: 

4) Put the System Master diskette in the drive, boot DOS, and 
from either BASIC type 

BRUM MASTER CREATE 

5) You should see the message 

[JOS 3. Z cV^riS-rhEflTE UTILITY 

OQWCIOMT 19OT &V *PPL£ COMPUTER IHC. 

RLL RICtHTS RESERVED 



<W3te tOrt>XNG DOS IKRQE> 

6) You'll then be told to type the greeting program name 
to be used by the converted diskette: 

FLBBSE INPUT THE GREETING PRDGWrS 



45 



We'll assume that when you SAVEd the revised greeting program on diskette 

ONE (step 3, above) you uncd the name HELLO. So type 
HELLO 

unless you wish the diskette to RUN some other progran name each time the 

diskette la booted. When you press the RETURN key to enter the greeting 
program now-, you'll see this me 



■«£**£* THftt »*=tSTEe DOES NOT CRErTTE 
(ME GR&T1N5 FWMRRM- OP PLACE IT IN 
TMfc I-IfrECTOSV 

THK FILE MrtME TMflT fctU- BE 
fLWCEC- WITHIN TMf IHftG£ 
HELLO 

*LfiC£ THE OSSKETTE TO BE H3STER£D 
THE DIfiK DRIVE 

PftC SETUfeO *♦€* RCfW 
MOTE IF VOU URNT ft DITFEFENT FILE ISflHE. 




Text Klnj 

8*ou4mtl.l Piles! 5o»* EmboI*. 

GPM(i>i» and <ILG6Slna Saouaatlal Mies 

VtlTCiBfl Scou.otl.1 Pi la* 

RgAOlng BMpaatUl File. 

Hare on StcpMiKLl m«»t a»bto «nd fosZTkon 

■yt.-lt* Off tor* 



7) Follow the Instructions. Remove the System Master diskette from the 
disk drive and replace It with the diskette you wish to convert — 
diskette ONE in this case* Finally, press the RETURN key to begin 
converting; the progran will Inform you when the process is complete. 

6) After using the MASTER CREATE program, always re-boot DOS before 
doing any other work. 



■t? 



*** Note *** 



mtZ 



The greeting progran name that you give to the MASTER CREATE program is not 
placed in the diskette's CATALOG. It just tells the diskette's DOS which 
program name to RUN each time the diskette is booted. You must make sure 
that the diskette's CATALOG actually contains a program bearing the same 
name you give to the MASTER CREATE program* 

If you forget to do so (by skipping step 3 above), you'll see the message 

FILE NOT FOUND 

each time you boot the disk using this diskette. 



•»= 



*** Reminder *** 
You must remember the name of the greeting progran for each diskette- 
Using the same greeting program name on all of your diskettes makes this 
easier. 
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TEXT FILES: AN INTRODUCTION 



Sometimes you'll want to use the disk to store information that is not a 
program* Yon may* for example, wish to keep copies of correspondence, a 
list of words ufted in a word-guessing game, intermediate results of a 
calculation, or a mailing list. A text file , sometimes called a data 
file will allow you to do this and more- The letter T marks text files 
in the CATALOG directory* 

Text files are created and retrieved using DOS commands in an Integer 
BASIC or Applesoft program. A text file may be created using a program 
written in one language and retrieved from a diskette using a program 
written in another language- 
Most sample programs in this manual are in Applesoft. If you wish to 
convert the programs to Integer BASIC, recall that in Integer BASIC you 
can't make string arrays and you must DIMension string variables. In an 
Integer BASIC command Such as 
INPUT AS, BS, CS 

only RETURNS (not commas) may separate the three responses. This manual 
does not tell you how to make each program run in Integer BASIC: see the 
Appendix M of the Applesoft II BASIC Programming Reference Manual for 
details of converting between languages. For some hints about changing 
the BASIC in which a program runs, after the program has been written, 
see page 76 of this DOS manual* 



m 
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The DOS commands LOAD and 
text file. An attempt to 



RUN (also BLOAD and BRUN) may 
do so will cause the message 
MISMATCH 

LOAD and RUN expect a BASIC program file (and 
Binary machine-language file), not a text Lie* 
write programs that 
using the DOS 



not be used with 



BLOAD and BRUN 
Instead, you 

send data to a text file and retrieve data from 

commands discussed in this chapter: 



FILE TYPE 

to appear 

expect 

must 

text file, 

OPEN 

CLOSE 

READ 

WRITE 

APPEND 

POSITION 

EXEC 

The commands OPEN, READ, WRITE, APPEND and POSITION cannot be used in 
immediate-execution mode. If you try to do so, you'll receive the message 

NOT DIRECT COMMAND 

These commands must be used in deferred-execution mode, that Is, from 
within a program. The commands CLOSE and EXEC may be used in 
inunediate~execut Ion mode* 

In addition to the commands listed above, the DOS commands 

LOCK and UNLOCK 

DELETE 

RENAME 

MON and tlOMON 

VERIFY 

CATALOG 

work with text files in the same way they work with program files. 



3 
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There an- <wo different types of text files: sequential text files and 
random-act-ess text files. Both types of text files store strings of ASCII 
C0d*i to represent the data* but in different formats- Diagrams of the 
two text-file types are shown below (the character ^ represents the 
RETURN rharacter, sent automatically at the end of most PRINT statements). 



"PICTURE" OF A SEQUENTIAL TEXT FILE 



Character 
ASCII 

File Byte 
Field 



IT l> |a It |>|o|n|e |> |*|l |o |w U I I 1 1 1 1 II 



155| 13| 65| 8M 13| 79|78| 69 1 13j66| 76] 79 |87| U 




"PICTURE" OF A RANDOM-ACCESS TEXT FILE 
( Example: Record Length 5, One Field per Record ) 



Character: J 7 > 
ASCII: 



*_I_iJ 







N 



E [> 1 |B |L |0 |W |> 



55|13|W|W|0fl|65|84|l3|gg|gg|79|78|69| 13|0g|ftn| 76 [ 79 [87 "[JTJM 



File Byte: 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 

Record Byte: 012340123401234012340 

Field: 

Record; 12 3 



The terms "field" and "record" will be discussed in Chapters 6, 7 and 8* 
The commands OPEN, CLOSE, READ, WRITE and POSITION are used with both 
types of files* but in somewhat different ways. Sequential text files are 
simpler to use and understand* in some respects, so we will discuss the 
use and structure of sequential text files first. The use of 
random-access text files is described in Chapter 8. More detailed and 
technical Information about all types of files can be found in Appendix C, 



SEQUBITIALTEXT FILES: SOME EXAMPLES 

Suppose you want to make a file containing a list of words to be used in a 
word-guessing game. Here are two pairs of programs that deal with such a 
file- The first program in each pair creates a text file on the diskette. 
The second program in each pair retrieves the data stored in the text 
Hie from the diskette* 

This program creates a text file named WORDS 1* containing the words APPLE, 
BAHAMA, CATALOG, DORMANT, EAGLE, FRUIT, GOOSE, HAT and ICICLE. 
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W'H MftKr MORE-51 
I »EM CTRL-t' 

PK1NT D*. "OPEN M0ROS1" 
INT M "MKITE MOWS!" 

PffINT "W*T_£" 
WJNT -BflNPWft" 

PRINT -CflTfiLGG" 

PRINT -W»MHNT-' 
P*INT -E«QL£" 

PRINT "FRUIT" 

PRINT "QQOSC" 

PRINT *HRT- 

PRINT -ICICLE" 

PRINT P»> "CLOSE WORDS!' 

END 



Line 3(1 OPENs the flic, using the normal format for sending 
from within a BASIC program. OPEN places a text file named 
CATALOG (if It was not there previously). 



a DOS copmand 
WORDS 1 in the 



Line Afl's WRITE command causes subsequent output from PRINT statements to 
be sent to the named text fll* Instead of to the TV screen. So in this 
program, each PRINT statement in lines 59 through 139 will send the word 
inside the quotation marks to the text file WORDS 1, and not to tha TV 

screen. 

Line 149 CLOSE* the file, and ends the file-writing process. 

if the program Is RUN and you're not in HONitor mode you won't see 

anything: usually DOS commands and disk input and output are not 

displayed. But if, as explained in Chapter 5, you type 

HON C, I, 

(or simply 

HON C, 

since no Input from the disk is involved) and then you RUN the above 

program you'll sec the following: 

CPEM WOK-SI 
HR1TE M3WS1 

HPPLE 



catalog 

DORMANT 

fcftGLE 

FRU1T 

GOOSE 

wot 

ICICLE 
CLOSE WORDS! 



± 
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At thLs point you'll have a file called W0RDS1 on your diskette. WORDS1 
will be marked with a "T m in the CATALOG to Indicate that it's a text 
file. The file consists of items of data (in this case* words) separated 
by KtiTUKNn. A RETURN character Is automatically sent at the end of every 
PRINT fltatement which does not end with a comma or a semicolon. Note that 
in this sense each RETURN la a character rather than an action — in 
particular, it is the character with ASCII code 13m 

Each item of data, ending with its RETURN character* is called a field . 
A field is stored in the text file as a series of characters represented 

by their ASCII codes- The last character in each field mist be the RETURN 
character, ASCII coda 13. 

WORDS I la colled a sequential tent file because each field is stored 
beginning immediately after the RETURN character of the preceding field. 
When stored on the diskette, fields nay be of different lengths: the word 
APPLE takes 6 bytes (one for each letter plus one for the RETURN 
character), KANAKA takes 7 bytes, and so on. A sequential text file is 
stored on the diskette as one long, continuous series of ASCII-coded 
characters, a chain of fields with no gaps left between them. 
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Once WORDS 1 is on the diskette, the question immediately arises, "How can 
I retrieve it?" The following Applesoft program will retrieve WORDS 1: 

IB REN RETWZEVE WC*tt>Sl 
D* - *-. BOf CTHt.~£> 

P*INT D»i -OPEN WCtfPSl* 

PfrINT W, *RERD MOfrDSl" 

rt» I - 1 TO 9 

INPUT ft* 

NEXT I 

S» PRINT t>*; -CLOSE HOttDSl" 
W END 

Line 3d OPENs the file; line 49 tells DOS that all subsequent INPUT or GET 
statements will refer to the named diskette file instead of the Apple's 
keyboard. It ts as if the disk were typing responses. Instead of you. 
INPUT command always causes one complete field , ending with Its RETURN 
character, to be "typed in" to the Apple. If another INPUT command 
follows. It will cause the next field to be read in, and so on. So 
lines 59 through 79 cause DOS to start at the beginning of words 1 and 
retrieve 9 fields which are placed in the array ASO), A$(2), A$(3), 
A$<M, ... AS(9). Line 89 politely CLOSES the file. 

If HON C, I, is not in effect when the above program is RUN, you will 



An 



see nothing on your screen* 
effect, you'll see 

OPEN **C*t>Sl 
RE«> MOM>SX 
Wfl-E 



But if HON C, I, (or just HON C, 1) i£ in 
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▼wn ' 

QODSE 
« 

A question mark ( T > la displayed before each INPUT from the disk, Juat 
as It Is before each normal keyboard INPUT. 

To check that all worked as claimed, try typing 

PRINT AS(2), AS(9>. A$(M 

and you should see the words BANANA — from A$(9) — then ICICLE and 

finally DORMANT. This Is a good way to check that information was read 

correctly. 



X 

If you 
DELETE 
vitb a 



modify Che program HAKE WORDS! to make 
WORDS I before re-RUNning HAKE WORDS I. 
mixture of the old words and the new* 



different words, be sure to 
If you don't, you nay end up 



Here's how to create a sequential file called WOAD52 containing the same 
words as WORDS 1 1 but with all nine words in one field. Each word is 
followed by a comma, so that an INPUT statement with multiple variables 
(9 t In this case) can be used to retrieve the separate words. 

10 REtt Hf*fcE UBftt>S2 

3* PRINT Mj "OFCN UORt* 
*0 PRIWT Dfc*i*ITE WOM>S. 

se print - apn,*. &***** c«t«lo 
a. 

I» PRlWT <" lXWW««T- £*Gtf FRul* 

79 FWJ«T - Q0OSE. HftT- - fc fc 

9» PtINT M; "CLOSE WDWySZ* 

Note that the PRINT command in line 59 ends with a semi-colon. A 
semi-colon at the end of a PRINT command stops the automatic printing of a 
RETURN character after the last data character* Therefore the characters 
sent to the disk by the next PRUT command will appear in the sage 
field with the characters sent by line 5(Ts PRINT command. The PRINT 
command in line 6(1 also ends with a semi-colon, so the field still docs 
not have its end-marking RETURN character- Line ?fl*s PRINT command ends 
without a semi-colon or comwa, allowing the automatic final RETURN 
character to be sent at last. This ends the field, which now contains all 
the characters PRINTed by lines 50, 6fl and 70. 
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Comma* In a disk-lews PRINT command usually send characters to defined 
lib-fields on the screen. However, commas do not serve this name 
fiirmatt Ink function in PRINT commands used when WRITEing to the disk: 
those roamms are treated at, if they were semi-colons, in PRINTing to the 
dfuk. Items separated by commas will be concatenated, with no intervening 
spaces Inserted. A comma at the end oE a PRINT command has the same 
effect as a semi-colon: no automatic final RETURN character Is sent. 

When the program HAKE W0RDS2 is RUN with HON C f I, in effect, you'll see 

DP£N MOW- 
WRITE UOfff<&£ 

ftm.e, etfWRNrt* catalog- txwwNT. EflBLC. 

FRUIT, GOPSC. HRT. tCICU* 
CLOSE MQRPS? 

This Applesoft program retrieves WORDSZt 

lft PEFt RETRIEVE MOW>S* 

ffl M • mm l REH CTRL-tf 

2fl PRINT Dfj "Of€N H0ROS2' 

40 PRINT D*; "RERP MOROSE* 

3» INPUT Rl*i rt£«, WW *«, MS, &** 

. «7*. AG*, R9S 
90 PRINT W.'CLOSC WDfitW>2* 
9» CNP 

When the above program is RUN with HON C, 1» in effect, you'll see 

©PEN MOR0S2 

? APPLE SflNflNft- CHTRLOG- PORfWNt, EftuLE 
- FttMjT, O0OSC- HOT. ICitXE 
CLOSE MCKD52 

In Integer BASIC, commas can separate multiple INPUT responses for 
numeric variables, but not for strlnR variables* Only RETURN 
characters can separate multiple responses when INPUT is used with 
multiple string variables- In Integer BASIC, therefore, the program 
RETRIEVE WORDS2 will assign the entire field (9 words, 8 commas and 6 
spaces) to the variable Al$. Then you will get the END OF DATA message 
when there Is no field to assign A2S. 



In Applesoft BASIC, you can also use the GET command to retrieve data 
a tent file, character by character. This has the advantage that you 
define any character as marking the end^of-word, for instance. The 
following Applesoft program also retrieves the text file WORDS?. 



from 
can 



In line 10, 
A£(l>'s) to 
CTRL-D (4 is the ASCII code for CTRL-D). 

(and un-copyable) control character. 



the CLEAR command sets all variables (Including 1 and all 
zero. Line 28 uses Applesoft's alternate way of setting D$ to 

This method avoids the invisible 
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ri*t i. 






|* 




s 








.. 






- i 






&* 






T>*N 


-. 


PS 7**E/i 




1 


) - E» 




W-T :* -^ 






GOTO W 






PBIfti G* (ft 




14* 







Line 80 CETs one character at a time from the text file W0RDS2, which was 
OPENed for READing in line* 50 and 60* If the new character is neither a 

comma nor a RETURN, line 110 adda the new character to the end of the 
string A5<I)* Then line 120 sends the program back to line 80, to GET the 
next character. Thus, the program builds up the first word, character by 

character, in A$(l). 



first word la ended, so line 90 sends the progr.im 
nt I and start collecting a now word In A$(2). 



tfhen a comma is found the 

back to line 70 to Increm 

And so on* Finally, a RETURN character (R5) marks the end of the field, 

so line 100 sends the program on to line 130 to CLOSE the file and end the 

program. Note the use of CHRS{13>, in line 30* You cannot directly type 

a RETURN character into a BASIC program line (a typed RETURN enda a 

program line), but CHR$(13) is a RETURN character in Applesoft* 

When GET obtains characters from the disk, these characters are not 
displayed on the screen, even in TON C, I, mode- Line 115 has been added 

to let you see the words as they are built up, character by character. 



After 

file, 

1) 



2) 
3) 



an Applesoft GET command takes i ta response from a diskette text 

the following problems arise: 

With NOMON C.1,0 the first character PRINTed after the GET 
will not appear on the screen. 

With HON C*I,0 the first character PRINTed after the GET 
will appear on the screen. 

In either mode, if a DOS command is the first item PRINTed 
after the GET, the DOS command may not be executed because 
the necessary preceding RETURN is missing. 



In the program GET W0RDS2, the non-printing "throw-away" character CTRL-A 
<TS) was placed before the first desired PRINT character in line 115. 
This takes care of problems 1 and 2, above* To cure problem 3, the RETURN 
character (R$) was placed before the PRINTed DOS command in line 1 30, muW. 
as was done with TRACE (see page 44)- 

When this program is RUN with HON C, I, in effect, you will sec the 
following (but all displayed in one column, not three): 
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rtfr 



WW 

r - 

I RMF M 



ITU 

CftTHL 
CATRLO , 



DO* 
DOfifl 

ooKm 
two*** 

DOWWWT 

E 
£* 

EftC 

E*QL 

FWLfc 

f 

f* 
eta) 

FRUI t 



ooo 

GODSE 

M 

MRT 

I 

IC 

IC1 

IC!C 

IC1CL 

ICICLE 

close mospss 



And lastly, 
words in th' 
third field 



here's an Applesoft program that creates a 
t first field, 3 words in the second field. 



file W0RDS3, with 2 
and 4 words in the 



id ffEri f*«e *c*t>S3 

»M« CMR» <*>: KETt CTW_-ft 

3* PtJMT t'*, "OPEN U0«>52" 

«i PftlHT t*- "MRITE «0*DS3" 

36 W?IN!f -«Pf*LE. BfiNPWFt" 

60 PRINT "C«Tm_O»3-D0MiRNT.EHQLe* 

?8 PfiINT "FffUIT. GOOSE/ HRT ■ JCf&E 



PRINT [•-* 



CLO^C MOTOSJ* 



The first field will contain 

APPLE, BANANA 

and is 13 bytes long, one per character (coraaB must he counted too) plus 

one for the RETURN character. The second field, 
CATA LOG , DORHANT , EAGLE 

Is 22 bytes long; the third field, 

KRUIT, GOOSE, HAT, ICICLE 

Is 23 bytes long. 



55 



so 

tag 
to 



When RUN with HON C, 1, in effect you'll see 

WRIT* W- 

M1 ■• :.;. IWVtftMM 

• ::L.H*T. ICICLE 

Here's a program Co retrieve WORDS3: 

10 F£« RETRIEVE WRT>S: 

J* p* - EHR* <«); REM trftL-0 

PRINT £■*; '•OPEN MORDS".- 

pf !NT &*; "REftO WORDS 
INPUT R*..S* 

tupvi r», i». v# 

INPUT 14*, X*> V», Z9 
PRINT t>», "CLOSE WORDS 
9B END 

When RUN with HON C, I, In effect, you'll see the following: 

OPEN MORDS3 
RC«0 WOPCS3 
?HPPL£, P«N**m 

STRCOG- BQRNANT. £«<€ 
?FRUIT, GOOSE- HRT, ICICLE 

OSE MORC- 

The programs to READ the sequential text files WORDS 1, WORDS2, W0RDS3 were 
carefully designed to READ exactly the correct number of fields and the 
correct number of items per field- In general, a program to retrieve a 
text file must be designed around the specific file. If you make a 
mistake, the results can appear somewhat confusing' For instance, 
consider the following "wrong" program to retrieve the words in text file 
W0RDS3- 



10 



4© 
50 
69 
7% 



REN RETRIEVE MOR[>S£ 
D* « ": REN CTRL-*- 
PRINT pjj -QfSN M0ROS3" 
PRINT 0*, "REAP M0R&S3* 

INPUT ft*. S* 

INPUT T*, I**. V* 

INPUT k», K*, vt 

PRINT r*«. "CLOSE WORDS? " 

END 



3 a 

■r 
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With HON C, I, in effect, here's what you would see on HUNning (he 
program. 

OPEN HORD53 
RCfiO M0RHS3 
VRPPLE.. BftNflNR 
KRTRLOO- IKWHRNT, ERGtE 
^FROtT, GOOSE,NflT, ICICLE 
ItXTRfi IGNORED 
CLOSE W0RDS3 

The INPUT command in line 70 cauaed the entire field containing 
FRUIT.GOOSB.HAT.ICICLE * 

to be READ into the Apple. The first three words were assigned to the 

f" 18 !! 1 ™,,™' XS and YS - BoE there ,s no variable corresponding to the 
fourth INPDT response, ICICLE, so the message 

EXTRA IGNORED 

is displayed, and execution continues. 

Hera is another "wrong" program to READ the text file W0RDS3: 

1» REM RETRIEVE HC*t-S3;C 
39 09 * ■■ REM CTRL-£> 
3* PRINT t>*., "OPEN MORC^ 
4© PRINT O^-RERP WORt" 

INPUT ft*, S* 

INPUT T*.tW.V*,M* 

79 INPUT X*. Y*.Z* 

80 PRINT &*, -CLOSE MOROS3' 
90 END 

And here 1b a HON C, I, RUN of the program. 

OPEN MORDS2 

RErt* HUftOSS 

^•PPLE. BONflNR 

rtTRLOO. DOftfWNT. EHQCE 

TTPRUtT, GOOSE. HRT. ICICLE 

>"TRft IGNORED 
f 

'43 0* PATR 
BREflh IN F9 

This time, line 60 caused the field 

CATALOG , DORMANT , EAGLE 

to be READ into the Apple. The three words are assigned to tho variable* 

TS, US and V$. But line 60's INPUT command expected four responses, so 

it causes the next complete field to be READ into the Apple: 

FRUIT.GOOSE, HAT. ICICLE 

The first word, FRUIT, is assigned to line 60's last variable, W$. There 

are no more variables with this INPUT command, so the message 

EXTRA IGNORED 
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is displayed, and execution continues. There are no more fields In the 
file, so line 7fl's INPUT covnand causes the 
END OP DATA 

message, iind the program comes to a stop. 

A somewhat More general pair of programs, HAKE TEXT and RETRIEVE TEXT are 
discussed In a later section. They Illustrate how to make a program sore 
adaptable to different text flics- 



OPBi-MG AND CLOSE- tJG SEOUBtTIAL Fl U=$ 

Sequential text files should be used when information is to be retrieved 
In a linear fashion from the beginning to the end of the file, and when 
Information does not require much updating or on-going revision- For 
example, a sequential file could be ueed to contain data for a 
word-guessing game, as in the preceding sample programs. 

To create a sequential text flle f the commands 

OPEN 

WRITE 

PRINT 

CLOSE 

are used* in the order 

other). To retrieve a 

OPEN 

READ 

INPUT 

CLOSE 

are used, again in the 

other • Both procedures 



shown (though not necessarily right after each 
sequential text file, the commands 



order shown though not necessarily right after each 
are Illustrated in the preceding section. 



A certain ritual is required before and after you create (WRITE) a 
sequential text file: before using the file you must OPEN it- When you 
done, you mist CLOSE it. The same is true when retrieving (READlng) a 
sequential text file: OPEN before READing, and CLOSE the file when you're 
done- 



re 



© 



Files that have been OPEKed must be CLOSEd. Failure to 
was OPEKed and written to by a WRITE command may result 



CLOSE a 
In loss 



file that 
of data. 



The syntax for these commands is similar to other DOS commands. 

( Note: OPEN and CLOSE arc also used with random-access files — see 

Chapter 8. J 



OPEN f [,SsJ 
CLOSE [fj 



♦ Ml (,Vv] 



Examples: 



OPEN SESAME 

OPEN SHOP, D2, 

CLOSE 

CLOSE MOUTHED 

CLOSE WINDOW 



S7 
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s: 



n 

± 




B 4 



T 



OPEN set* aside workspace in the Apple for the file f (for those who know 
about such stuff, OPEN allocates a 595-byte file buffer to handle this 
I lie's input and output), and gets the system ready to read or write from 
the beg innin g of the file. OPEN also sets up the slot and drive numbers 
to be used by the subsequent WRITE (or READ) command. 

Hi. CLOSE command releases the workspace in the Apple (de-allocates the 
flic buffer associated with the file f). If f is not specified, all OPEN 
files will be closed, with the exception of any file being used by the 
EXEC command* EXEC files are discussed later in Chapter 7. OPEN 
sometimes CLOSES too: OPEN first checks to see if the named file is 
already OPEN; If so, it CLOSEs It before re-OPENing It. 

Note that the CLOSE command has no Drive or Slot parameters. If you type 

CLOSE MYFILE 

then any file named KYFILE will be CLOSEd, regardless of the slot and 

drive number associated with the file. Siollarly, the coontand 

CLOSE 

will CLOSE all files (except a file being EXECed) on all disk drives. 

In various circumstances, you My wish to delete a file f that may or may 
not exist* This is especially important to avoid problems of overwriting 
an old file (unless you overwrite the entire old file, part of the old 

file will remain, attached to the end of your new file)- Suppose a game 

creates and uses the file 5CORE5 each Mae It is played, and you wish your 

program to delete any old file by that name at the start of each new game. 
The command 

DELETE SCORES 

will cause the error message 

FILE NOT FOUND 

if the file doesn't exist, and your program will halt. 

to delete any file named SCORES and re-OPEN it for new 

not that file already exists: 



Here's a quick way 
data, whether or 



5 *£W 
SB 



": RE* ft* IS CTRt»t> 
WWT M. "OPEN ftC-OftES" 
PRINT D»; ^DELETE SCORES* 
PHtHt p** *OPEM SCOWS* 
REM 

KEM6IMECK OF PROGWW 



WRITC-ING SEQUB4TIAL FILES 

Mere is another program which creates a sequential 
Applesoft program creates a text file named SAMPLE 
string!i and 10 numbers- 



text file. This 
which contains 3 



The Hie SAMPLE may or may not already exist each time the program is RUN; 
Lf it does exist, it should be DElETEd so as to remove old data from the 
file. If it does not exist and your program tries to DELETE It, you'll 
receive the Message 
PILE HOT FOUND 
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and the program will atop. Lines 29 and 38 take care of the probleat. If 
SAMPLE already exists, line 2fl OPRNa it and line 3(» DELETES it. If SAMPLE 
docs not exist, line 29 creates a file SAMPLE and line 30 DELETES it- 
When line 40 Is executed it creates a clean new file SAMPLE, ao the 
problem of mixed files is avoided. 

*tn nHH£ SftMPCC 

1W f-« - CHHt <*>: R€* CT«.-t> 

W?IWT [*. "OPEN SflWPLE" 
3ft WSJNT D*; -DEIETE SWPL£" 
■»** punt p»j -oPtft s»*ve*' 

SB *"RlNT 0«.°t«lTg SAMPLE" 
t« PRINT "HI MO": f*I*T "MJ Ho- 
i's PHINT "OFF TO THE PISK ME 00" 
80 FOR J • i TO IB 
» FfrINT ^ 
IBB NEXT 3 

110 W?l«T 0«; "CLOSE SWPLC* 
X2B END 

Here's what you see on the acreen when you RUN this program. If MOW C, I, 
is in effect. 

DELETE S*r*t£ 

OPEli SrtNPLE 

WRITE SfM»LE 

MI HO 

HI HO 

OFF TO THE VISK ME GO 

1 

2 

3 

3 
6 

7 

» 

IB 

CLOSE SW1PLE 



Before you WRITE a file. It 
when you're done. Both the 
file name . 



t be OPENed; CLOSE it (quietly, please) 
OPEN and WRITE coaoands must refer to the same 



Once a WRITE command is executed, any subsequent PRINT commands send all 
characters to the diskette, instead of the screen. A WRITE command is 

cancelled by the use of any DOS command in a PRINT atatement. Even the 
"empty" DOS oomnand (just CTRL-0) will do. 



E 
E 
E 



:• 
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3 
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=1 



An INPirr command of the form INPUT X$ also cancels a WRITE command, hut 

only after storing as the last text file character the ? which the IKPUT 

command normally displays on the acreen. If the form 

INPUT "WHAT'S YOUR NAME? "; XS 

Is used, the WITH is canceled after the characters In the string are sent 

to the diskette* 



© 



An error message cancels a WRITE command* but only after the entire error 
message Is stored as the last field In your text file* 



The syntax for the WRITE command when used with sequential files is: 
WRITE f 
[Note; WRITE is also used vith random-access files* see Chapter 8*] 



Examples: WRITE LETTER 
VRITE RIGHT 



The sample program given at the beginning of this section is a simple 
Illustration of the most basic (BASIC?) elements needed to create a text 
file. A slightly more general Applesoft program called MAKE TEXT is on the 
System Master diskette that cans with your disk drive. 

MAKE TEXT allows you to create a sequential text file containing up to 100 
strings; each string may have at most 239 characters. Try It — you'll 
like it (we hope). Place the System Master diskette in your drive and 
type 

LOAD MAKE TEXT 

A LISTlng of the program should look like this: 

" -. 

is dim f>r i©e:«. l - & 

) D* * CHW C4> REM CTRl t> 
WJW£ te: 

rVT »VW GET TO TVP€ ONE ST 
M W TIME 
Ptilfft "fl STRING MftV HAVE if* T 

333 eMMWCTfiftS. " 

II "TWJS PROGRftM LETS VOU 
Mitt. TEXT FILE 

rJT :1 * J * % 

PES5 T>E RETURN I 
DUIt > 

*tyfe smima **j i " ri - 

( Continued on next page ) 
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(Continued froa previous page) 



, 



■ 



^J 



•t* 



ro i - t 

Once the program Is LOADed* SAVE it on a diskette that's not write- 

protected. (This step Is necessary because this prograa* like the ANIMALS 
program discussed In Chapter 4, creates a new file-) 

Is MAKE TEXT still In your Apple? And a non-write-protected diskette in the 

drive? If so* type 

HON C, I, 

so you can see the commands sent to and fro» the disk- Then type RUN 

and you should see the following message: 

VOU OCT TO TYPE GWE £TJ*J«G AT A I 

fl ST*J»3 WW HfiVE UP TO 

THIS PROGIW: LETS VOtt WRITE TEXT FtUt 

fP»£SS THC RfiUWN KEY FQ RUM ' 
TV*»£ STftlHQ «■ 

Type In as nany strings as you like (up to 100 may he entered)* Warning: 
the program uses INPUT, so don't type comnafl or colons into your strings. 
When you wish to quit, just press the RETURN key Instead of typing a 
string. You'll be asked 

MH«T FILE NRHE? 

Choose a name for your text file, press the RETURN key* and as your strings 
are seot to the disk you'll see then printed on the screen- First will 
appear the disk commands 
OPEN f 
DELETE f 
OPEN f 

WRITE f 

(where the f is replaced by the file name you chose). They'll be followed by 

a number — the number of strings you entered into the file* (This 



4- 

a«4=i 
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number will bo «Bcd by a program discussed In the next section that 
retrieves your Tile). Next you'll »ce your strings. Finally you'll Bee 
(be nu>RHnf(c 
CLOSE f 

Here's a sawple HUN of the MAKE TEXT program: 

THIS PRGWNW LETS VOU WRITE TEXT FILES 

wau get ro tvpe one string »t ft Tine 

ft STKJNG HHV HRVE UP TO 235" CHHRWCTERS 



CTO SUIT. PRESS RETURN KEY FIRST, 
rVPt STRING »,l. MERE'S STRING 1 

<T0 SUIT- PRESS RETURN *EV FIRST. 
1YP€ STRING »2 NND NV SECOND STRING 

(TO SUIT, PRESS RETURN KEY FIRST > 
T»T>E STRING *2; ON ME SO 

CTO QUIT, PRESS RETURN KEV FIRST' 
tve^ STRING •* ENOUGH «_RE« 

(TO QUIT, PRESS RETURN KEV FIRST". 
TVPE STRING »5 

MHRT FILE NnME? TEST 
OPEN TEST 
DELETE TEST 
OPEN TEST 
WRITE TEST 
« 

HERE'S STRING 1 
**■■ rfv SECOND STRING 
ON ME GO 
ENOUGH RLRCncV' 
TSE TEST 



© 



If you OPEN a text file that already exists and then WRITE to it (without 
first DEl.ETElng the file and re-OPENlng lt)» then you will overwrite at 
leant a portion of the file. Unless you overwrite at least as many 
characters as existed in the old file, the result is that the new file 
contents will be a »lx of the data PBlKTed to the file on the two 
occasions First will appear the new characters you PRINTed to the file 



v 
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this time, and then will follow any portion of the old file you did not 
overwrite* To clear all character* from the old file* OPEN and DELETE the 
old file before you OPEN it anew, (In the program MAKE TEXT, lines 140 
and 1^0 take care of "cleaning out" any previous test file by the same 
name*) To keep programs from overwriting a file. 1ACK the file. 



READ-MG SEQUBIT1AL FILES 

The DOS command READ allows you to retrieve a text file. Once a READ is 
executed, any subsequent INPUT statements (or GETs in Applesoft) refer to 
the specified file instead of the Apple's keyboard* This Applesoft 
program retrieves the text file SAMPLE created by the program listed at 
the beginning of the preceding section. READ, like WRITE, must 
preceded by OPENlng the file to be used. The file must be 



be 
CLQSEd as well. 



s 


REM RETRIEVE SflMPLE 


if 


M - : Ken 




is , -..-, 




PWINT (**< -OPEN SfflPLE" 


w 


Wl*T 0**-ftEAO SflMPLf- 


4* 


IWVT f*9, B»j C» 


90 


FOR I - 1 TO 16 


«© 


IWUT W 


TV 


w?:r i 


PD 


PVltfT f^'TlDSP <MWW g* 



00 



An OPEN must precede a HEAD, and an INPUT (or, in Applesoft. a GET) 
follow a READ. The OPEN and READ must refer to the sane file nan*. 
you RUN the program with HON C, I, In effect you'll see this: 

OPEN 5»*tPUJ 
«EflC» SBWLE 
*U HO 

HI NO 
T^OFF TO THE 015J 
1 



7S 
■ 

?» 

urn 



must 

If 



*fl«PL6 



The program was written explicitly with the SAMPLE file in mind: it 
assumes that the text file contains 3 strings, (AS, BS, and CS in line 48) 
and 10 Integers (U in line 60). Two question marks are printed when BS 
and CS are INPUT because RETURNS separated the INPUT's multiple responses. 
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A RRAD command Is cancelled by the use of any DOS command in a FR1KT 
statement- The "empty" DOS command (jufit CTRL-D) will do Just fine. Use 
of the Vftf or IHt commnim «Uo cancels a READ. 



The syntax for the READ command Is the same as for WHITE: 

READ f 

(Notes RBAp is also used with random-access files* see Chapter 8*1 



Examples: READ LETTER 

READ CAREFULLY 



x 



Stopping a READ In Applesoft using CTRL-C will generate a string of 
REENTERS. To avoid this, press the RESET key to stop the program. 

An Applesoft program that retrieves teat files created by the MAKE TEXT 

program Is on the System Master diskette. Place the System Master diskette 

in your drive and type 

LOAD RETRIEVE TEXT 

then SAVE the program on the same diskette you used for MAKE TEXT. (The 

program is really a companion piece to HAKE TEXT, and It's simply more 
convenient to have them on the same diskette.) 

A LISTing of the program should appear as follows: 



12 Ft ■■': 



B ■ 
FILE 

Alt 

(tQORRtt 



^H i 



SO INPUT "frfWE Of 1 

* 
22 PRINT [>» "HON 



F-FINT !'♦-. ''OPEN "J S» 
■ "RE«£i '. It 

ii'tn ft* 

FOR J - I TO I 

re jMftir a« 

». i ct : _ c 'i z* 



■»=) 
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Now type 

HUN 

and you should see the message 

THIS HH RETRIEVES TEXT FILES 

tfV THE rWl TEXT PROORAR 
HUN C 1,0 IS IN EFF£- 

**1E OP TEXT FILE* 

Type in the name at the text file you created using the MAKE TEXT program, 
preen the RETURN key, and you should be off and running (oops — rather, 
READlng). 

Here's what you'll see tf the file TEST, used as a sample at the end of 
the last section, is retrieved using the RETRIEVE TEXT program: 

THIS PROGRAM RETRIEVES TEXT FlLf 
CREATED PV TTC 'NRKE TEXT' PROORfln. 
NGN CM. IS IN EFFECT 

WNE 0* TEXT FILE' TEST 

OPEN TEST 

REP*> TEST 

74 

THERE'S STRING 1 

7ntr> «v second string 

?ON HE GO 
?ENQUGH flLREfcr 
CLOSE TEST 
NOMON C, I'O 



MORE ON SEQUBITIAL FILES: APPBID AND POSITION 

The DOS commands APPEND and POSITION, respectively, allow you to add text 
to the end of a sequential text file, and to accesa information fro* any 
specified field within a text file- 

APPEND allows you to add data to the end of a sequential text file* 
This is particularly useful if you wish to extend the information in a 
sequential text file, as in the ANIMALS program discussed in Chapter 4 
could have- The command OPEN* you will recall, always sets the 
posit ion-in-the-f ile pointer to byte 9 y the first character in the file* 

The command APPEND performs an OPEN for you on a file that already 
exists, then sets the position-ln-the-f lie pointer to one byte beyond the 
last character in the file* 

The following program builds a file called TESTER that contains the two 
strings "TEST fl" and "TEST 1": 



i 

'r 

3! 
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T 



• HttW 
•VINT l>9< 
S# PRINT 
4*» PRINT 
;** PRlNl 
£*> PRINT 

re> print 



■ 

t*> REM CTRL-D 
OPEN TESTED" 
IT "dELETE TESTER" 
O*. "OPEN TESTER" 
(.*- -WRITE TESTER- 
"IXST »- 
■TE 
M -CLOSE TESTER" 

the strings 



"TEST 2", "TEST 3" and "TEST 4" 



JO 

4» 
3*> 



OB print 
The following program APPENDS 
to the file TESTER: 

3 REN RPPCM rSS ICR 

W - CHRJ * RE" CTRL-© 

PRINT f>#> "ftPPENP TESTES* 

PRINT «j "URITE TESTER" 

PRINT -TEST Z* 

PRINT -TEST 3T- 

PR1NT "TEST 4" 
7» PRINT P*-' "CLOSE TESTER" 



The following program displays the file TESTER: 

10 REN RETRIEVE TESTER 

2© D* « CNR* <4.v REM CTRL-D 

3« PRINT P*. "OPEN TESTER" 

40 PRINT P*; "REAP TESTER" 

S» FOR I - 1 TO 5 

INPUT M 

7» NEXT I 

GO PRINT B*. -CLOSE TESTED 

APPEND mist be followed by WHITE (attempting to READ will just cauae the 
END OF DATA message). The syntax for the APPEND command is doubtless 
familiar if you've been reading straight through this manual: 
APPEND f l.Sa] |,Dd] I.WJ 

APPEND, even though it is used only for WRITEing Into a text file, does 

not cause the 

KILE LOCKED 

message if the file is locked. That message is given only if you attempt 

to actually URITE to the file. 

The DOS command POSITION allows you to WRITE or READ information beginning 

in any given field of a sequential text file. The syntax for the POSITION 

command is 

POSITION f [.Rp] 

where Rp is the Relative-field position. This command specifies that 

DOS' posltlon-in-the-file pointer will be moved forward (only) to the 

p-th field ahead of the current pointer position. If p a 0, the following 

READ or WRITE begins In the current field. If p"l. the following READ or 

WRITE skips the current field and begins to the next field. If p-Z, the 
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following READ or WRITE skips two fields including the current field, 
before beginning to READ or WRITE. And ao on. If your file does not 
contain any field corresponding to the relative-field position specified 
by the POSITION command, the Message 
END OF DATA 

will be displayed, and program execution will stop. 



POSITION with the Rp parameter specifies a relative field position, p 

fields ahead of the current field. POSITION must refer to a file that 

have already OPENed. OPEN automatically sets the poBitlon-ln-the-f lie 

pointer back to the beginning of the flrat field. Thus, if POSITION Is 

used immediately after OPEN, the relative -field position also 

corresponds to the actual , or absolute, field position. In no other 
case is this true. 



you 



Like any other DOS command, POSITION cancels a READ or a WRITE. 
POSITION must be used before the associated READ or WRITE. 



Therefore 



POSITON actually scans the contents of the file, byte by byte, looking for 
the Rp-th RETURN character. If, during this process, it encounters an 
"empty" (value 0) byte, the message 
END OF DATA 

Is presented immediately . 
any such null character. 



It is not necessary to actually INPUT or GET 



Here is a program that uses POSITION to retrieve various fields from the 
TESTER file, created earlier by the MAKE TESTER and APPEND TESTER 
programs: 



io 



7* 



«Eft POSITION TESTE* 
t>» w CM*1 t4>; REM CTWL-C' 
PRINT D». "OPEN TESTE*" 
FWIWT [»«.. "POSITION TESTfcB-Ra*' 
PEW TESTE*" 



■■■• 
Llfl 



#*»NT 
INPUT 

PRINT 
PRINT 
INPUT 



t't, 



SIT JON TESTER, KV 

'«**» TESTER" 



PRINT P«. "OPEN TESTER- 
PR MIT £*», "POSITION TES*tRrRJ 



120 PRINT D»: -READ TESTE*" 
53* INPUT C* 
148 INPUT E* 

IS* PRINT P*. "CLOSE TESTER" 

If you RUN this program with HON C, I, In effect, you will see: 
OPEN TESTER 
POSITION TESTER- R2 

t«0 TESTER 
TE5! 2 

POSITION TESTER' Rl 



6B 



± 



mTX3 

* 



RivNP !L' Ith 
1ES1 « 
UMeN v* 

ION Tl R> 

RfcfW rESTER 

4 
CLOSE TESTER 

Are you surprised at the results? 

relative-field position number 9. 

one field to be READ into the Apple, and advances the 

position— in-the-Cile pointer to the beginning of the next field. 



Remember that the current field is 
Also, remember that each INPUT causes 



BYTE-BNG OFF MORE 



Note: the following section is not for beginners, and sequential files 
can be used perfectly well without a knowledge of the parameters discussed 
here* 

The DOS commands WRITE and READ can be used with a Byte parameter to 
WRITE or READ information starting from any place in a text file •* JX 
you know where that place is- The trick Involves knowing at exactly which 
byte in the file you want to start (each byte contains one character's 
ASCII code). To do this* you must know exactly how you have stored 
information into the fil*. You mist count all RETURiHs, commas, spaces and 
other characters in the file when figuring out where to begin- The 
problem is even more difficult for WRITE, because you Bust also know where 
to end- 



The B paraDeter is an actual or absolute position in the file unless R is 
specified* If R la given, the B parameter Is the actual position within 
the specified field - 

The command 

WRITE THISHONTH, B27 

sees the position-in-the-f ile pointer to the twenty-eighth byte of the 
file named THISHONTH (the first byte is number 9). Characters sent to the 
disk by a subsequent PRINT command will replace an equal number of 
characters that already existed In the file, beginning with the character 
in the 28th byte- 



x 



This over-writing is not confined to the current field. If you PRINT 
fewer than the number of characters remaining In the current field, you 
will create two new fields: the field you Just PRINTcd, followed by the 
tail-end of the field you were overwriting* If you PRIBT more than the 
number of characters remaining in the current field, you will over-write 
some of the characters at the start of the next field: the current field 
will then he longer, and the nest field shorter than before- 
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It is also possible to WRITE into bytes that are beyond the last byte of 

on existing sequential text file- An attenpt to READ the Intervening 
im*vfl ttvn bytes will cause the 
END OF DATA 

message to be displayed, and your program will atop* See the discussion 

of READ with the B parameter, for information on accessing sequential text 
(lie fields that ore not next to each other* 



which characters sent by 
characters. The default 
b is an actual, or 



The syntax for this command Is 

WRITE f | t fib] 

where the B parameter specifies the file byte at 

the next PRINT command will begin replacing file 

value of b Is 0, the first byte In a file. Byte 

absolute, position within the file. The B parameter may specify a 

position either before or after the current position-in-the-f lie pointer* 

[Note: this command is also used with random-access files* See Chapter 8*) 

Similarly, the command 
READ LASTKONTH, B32 

sets the posltion-in-the-f lie pointer to the thirty-third byte of the file 
named LASTHONTH (again, the first byte is number 0). A subsequent INPUT 
command will cause all characters in the next field (i.e. up to the next 
RETURN character), beginning with the character whose ASCII code is stored 
in the file's 33rd byte, to be READ Into the Apple. If the 33rd byte does 
not contain the first character of a field, only the remaining characters 
in that field will be READ. 

Syntax for this command is 
READ f [,Bb) 

where the B parameter specifies the file byte where the next INPUT or GET 
command will begin reading characters* The default value of b is 9, the 
first byte in a file* Byte b is an actual , or absolute, position within 
the file. The B parameter may specify a position either before or after 
the current position-in-the-f ile pointer. I Note; this command is also 
used with random-access files, sec Chapter 8- 1 

The following program sets the positlon-in-the-f ile pointer to byte 14 
(the fifteenth byte) in file TESTER, which was created earlier by the 
program MAKE TESTER. Then it WRITE* the string "APPLE COMPUTER". Note 
the familiar sequence: OPEN, then WRITE and PRINT, and finally CLOSE. 

5 REM BVTE WRITER 

1BW * C**» «*>-- SftK CTRL-D 

29 PftltfT ir.*.:"OPt* TftSTW 

3» PHIHT D*>"MRfTC TESTE*- B14* 

» PRINT &** "CLOSE TC£TES P 

With HON C, I, in effect, RUN RETRIEVE TESTER to see how the previous 
program has changed the file TESTER- As you can see, the field containing 
APPLE COMPUTER has completely over-written the fields that contained TEST 



* 3 
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1 and TEST 4. as well as the first character of the field that contained 
TEST %, As there are now only four fields In all, the END OF DATA message 
was displayed after the fifth INPUT command. 

The following program sets a pointer to byte IB In the file TESTER, just 
modified by the preceding program. Then this program READb to the next 
RETURN In the file. Again the familiar formati OPEN is followed by READ, 
next come INPUT statements (or, in Applesoft, GETs may be used) and 
finally the file 1« CLOSEd. 

5 KEM BVTE REflOCR 

18 W - CHR« <•»: RE* CTBL-0 

20 P*lf*T ftfe-OPCN TESTER" 

3» PRINT F>*; "REM* TESTER. B10" 

«*» 1WUT ft* 

50 PRINT C-i "CLOSE TESTE*' 

Try to predict what you will see, before you RUN thiB program. 
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Controlling th« Apple via t Teat fiU; EXEC 

Creating *fl CXfiG til* 

Capturing 7rogr«a» In « Text Fila 

Converting fUcMn«~L4aguag* Rautlnea to 5A5IG 
MAXFILES and lnt*ft»r BASIC Program 

EXtWuttv* Se*eloc 



72 








To better understand the contents oE this chapter* It is suggested that 
you first read Chapter 6, on sequential text files- 

CONTROLLING THE APPLE VIA A TEXT FILE: EXEC 

The DOS comaand EXEC Is similar to RUK t except that the disk file used by 
an EXEC command is a text file that contains commands or program linew, 
including BASIC statements* aft if they were typed at the keyboard. 

To initiate a demonstration of some EXEC command abilities* 

LOAD EXEC DEMO 

from your System Master diskette and then SAVE it on a diskette that's not 

write-protected. Leave the un-write-protected diskette in the drive* 

since the program WRITES a text flit. 

Next RUN the program. You should see the message 

EXEC CCWO » 

mis PROGRAM CREATES R S&aJtSHTIHL TEXT 
FILE MftnCC- "DO £R" CONTRINIMG £C«ft«L 
STtffHQS, £*CH fl LEOHL WPLE II COftWC- 
WEN VOU TVPfc 
EXEC W3E» 

TWN THE COMtnNfrS EH FILE M>"ER T«;£ 
CONTROL OF VOL* UfflPUTEJl E*CH COnMRND 
MILL BE EXECUTED JUST «S IF 17 Hflp BEEN 
TVW:J> *T TME (TCVeWWO. THE DOS MHNUHL 
DESCRIBES TME PROGRflH IN MORE DETAIL 

HflPfV EXECUTING » 
PRESS THE SPACE *W* TO f«*£ THIS 
PfCQQKfrt C*et«TE TME FJLE WE* 

IF VOU WISH TO .STOP THIS PROGtt*f NOW- 
VOU Hfty F*E5S T>C ESC KEV. 



Press the Apple's space bar, and after a 

disk drive's IS USE light come on as the 

onto the diskette. How type 

EXEC DO'ER 

press the RETURN key. Vour Apple will begin 

the script in the DO'ER file* 



brief pause you should see the 
program writes the DO'ER file 



a solo performance based 



un 



Here's a brief summary of the major things DO'ER does: 

First DO'ER issues a MON C f l t comand, so you'll be able 

to see what hsppens. 
Second, a three-line program Is written and saved on diskette 

under the name NEW PROGRAM!! The program is then LISTed. 
Now a FOR-NEXT loop is executed to take up some time, so 

you get a chance to look at the screen before the 

activity continues. 
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Ntfl DO'ER uses the INT command to enter Integer BASIC, 

LOADs the program COLOR DEMOS, and LISTs it* 
At this point, DO'ER uses CALL -155 to enter the Monitor and 
executes some machine-language instructions before using 
the FP command to enter Applesoft- 
From Applesoft a MON C,I,0 command is executed, then 

NEW PROGRAM! 1 is RUN, modified, LISTed (again a FOR 
loop allows you to take a look at the acreen) and SAVEd 
using the name EVEN MORE RECOCT PROGRAM 1 1 
Lastly, the program NEW PROGRAM!! is DELETEd and the CATALOG 
(Including the new addition EVEN MORE RECENT PROGRAM!!) 
is displayed. 
And you won't even have to lay a finger on the keyboard (unless your 
CATALOG has more than 18 entries, In which case you need to press the 
space bar to see the balance of the CATALOG entries). 



CREATMGAN EXEC FJLE 



Here's a step by step example to illustrate how to create an 
named DOIT that contains the following commands: 



EXEC file 



LIST 29, 
RUN AWAY 
CATALOG 



50 



First create and SAVE an Applesoft program called AWAY to use in the above 
demonstration* 



"i REN RMAV 

lft PRINT 1HRV #Mnv 

OUM" 



WITH RUM BV 



Next write and SAVE the following program, called HAKE EXEC, that will 
create a text file called DOIT. When you later EXEC DOIT, the commands 
your HAKE EXEC program has PRINTed into the DOIT text file will tell Apple 
to RUN the AWAY program for you. Notice that the commands which are 
PRINTed into the DOIT file, for later EXEClng, are not preceded by a 
CTRI.-D- 



REM CHK»<4> IS 



«n »*£ exec 

W W - CMR» <4> 

CTSL-P 
20 PRIKT »j "OPEN DOIT* 
3» PRINT W; "WRITE DOIT" 
48 PR1HT -LIST 29,39" 
S9 PRINT "RUN RHftV" 
GO PRINT "CRT«LOO* 
79 PRINT t>*. "CLOSE PGIT" 

After you have HAKE EXEC and AWAY both SAVEd on a diskette, type the 

command 

RON HAKE EXEC 

to create a sequent lal text file named DOIT. 
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Type the command 
EXEC DOIT 

to cause the commands In the file DOIT to be executed one by one, Just as 
if they'd been typed in from the keyboard* Again, notice that the 
commands now being EXECuted were not, preceded by a CTRL-0 in the program 
HAKE EXEC. First lines 29 through 50 from the program currently in memory 
(probably the program MAKE EXEC) are LISTed. Then the program named 
"AWAY" is RUN, and finally the CATALOG on the dlekette is displayed. 



CAPTURING PROGRAMS M A TEXT FIUE 

Here's a far more useful example of using the EXEC command: it allows you 
to capture program listings as text files. Such a program can be used for 

* translating Integer BASIC programs into Applesoft 

* renumbering parts of programs and EXEClng them anywhere 
Into another program 

* Inserting favorite subroutines into programs from a 

subroutine file on the diskette by EXEClng the file 

* "appending" one program to another 

* repairing programs that have become partially unreadable 
{you can capture th* good portion in a text file, re-boot, 
then EXEC the program portion back into memory) 

The line numbers 227(1 and 5139. following the LIST command In line 
the CAPTUKE program, should be replaced by the line numbers of the 
in memory that you wish to capture* The name of the sequential text 
containing the listing Is LISTING. 

1 REH CrtPTl*E 

2 t>» * £*** <4>: BCK CTKL-C* 

3 P*I«T M> "OPEN LISTING" 

4 «MNT Mi -URITt LISTING" 

5 POKE 33* 39 

6 list rare, $i2& 

T rmXHT D*j -CLOSE LJSTItfQ" 

e text , ENb 



6 of 
program 
file 



We made the line nu 
can add these lines 
your program that you 
easily put all the 
your program. 



bers of this program very close together, so that you 
to a program already in memory, or anywhere within 
have eight free line numbers. Tou could Just as 
lines of CAPTURE above the highest numbered line in 



CAPTURE creates a text file containing commands that are preceded by line 
numbers. When you EXEC that text file, the numbered commands will not be 
executed. Instead, Just as if you had typed those lines in from the 
keyboard, the lines are stored as a program In Apple's memory. Once 
captured in a text file, a program can be modified and then EXECed back 
lino Apple's memory. Unlike LOAD or RUN, EXEC doea not delete a program 
that If* already in memory. Using CAPTURE, you can capture a program in a 
roxt file from one language, then EXEC the program back into another 
language {of course, the program may not run without some changes — 
there's somewhat different syntax for Integer BASIC and Applesoft). You 
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can also use EXEC this way to add new lines to an existing program in 
memory. In fact, you can save a listing of CAPTURE in a text file named 
LIST SAVER, say, and then EXEC LIST SAVER any time you wanted to add the 
CAPTURE program to a program in memory. 



CONVERTING MACHME-LANGUAGE 
ROUTINES TO BASIC 

Here's another useful program that will take a machine- language routine 
and convert It into a BASIC program portion which POKEs the 
machine-language routine Into memory. The program portion can be used e 
part of either an Applesoft or an Integer BASIC program, to put the 
machine-language routine into memory each time the BASIC program Is run. 



S REM 

15 



23 
JO 

48 
v 



COt*-P0K£S WRITE* 
": REM CTRL-* 

print w> "open ctioe-fOKES- 

PRINT t>*> "t*LETE CODE-POKES' 
PRINT Of. -OPEN COPC-POKES" 

print r>«- -write cocc-pokes- 



•■■» 



m 

118 

133 

14ff 



FOR MCE - 7S9 TO ?»3 
COUNTER - COMTEK » 1 

IP COUNTER - 10 THEN COUNTER - 

1 
IF COUNTER C > 1 THEM 120 
PRINT 

PRINT L1NEMUMBER; 
UNENUWBER - LINEMUNBER * 1 
PRINT - POKE "> PUftCE.^ -. -- P£r* 
CPL«C£>* " 
NEXT PLRCE 

PRINT &*: "CLOSE COOC-PWES*' 
END 



When you use this program, the number in line 40 should be changed to 
contain the line number of your BASIC program where the POKEing program 
portion Is to start. The FOR loop in line 59 should contain the starting 
and ending decimal memory locations of the machine- language routine you 
wlah to convert. 



the 
the 



program, 

command 



HUNning it will create the te*t file 



Once you ve typed in 

CODE-POKES. Now use 

EXEC COPE-POKES 

to place your machlne-language-POKEing program portion into any other 

program, beginning at the line number previously specified. The program 



CODE -POKES WRITER will work with either Applesoft or Integer BASIC. 
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MAXFILES AND INTEGER BASIC PROGRAMS 

Aii EXKC file must be used If you want to increase MAXFILES from inside an 
Integer BASIC program without erasing your program* Here's how. Use the 
procedures described above to create an EXEC file, let's call It FILE-EX. 

P1L£»KX should contain the following commands to allow for 5 files on a 
system: 

MAXFILES 5 
WAD PROGRAM 
DEI. 10, 20 

HUN 

The first lines of the program would be as follows; note that what appears 
as CTRL-D is created by holding down the key marked CTRL while typing the 
letter D. 

10 PRINT "CTPJ--D EXEC FILE-EX" 

20 END 

30 REM MAIN PROGRAM 

EXEC-UTtVE SESSION 

The usual syntax for the EXEC command is 
EXEC f 

where f is the nave of a sequential text file containing BASIC commands or 
program lines- Examples of this usage appear throughout the earlier 
sections of this chapter* EXEC with this syntax causes the first field of 
file f to be read into the Apple as if it were being typed on the 
keyboard. When the first field's RETURN character la "typed 11 , the Apple 
attempts to execute the field's contents as a BASIC command, or enter the 
field's contents as a BASIC program line. The type of BASIC (Integer or 
Applesoft) is not changed by EXEC unless the file contains an FP or INT 
command* When execution has ceased on the first field, the second field of 
file f is read into the Apple and treated similarly. The action comes to a 
stop when the last field of file f has been read- 

The EXEC command cannot be stopped by CTRL-C* 

Only one EXEC file can be OPEN at any one time. If you are EX EC i rig a file, 
and one of the commands thus executed is another EXEC command, the first 
EXEC file ts immediately CLOSEd. Thereafter, it Is the second EXEC 
command that la being executed. 

If a file being EXECed contains a command to RUN any program, EXEC will 
wait patiently until the program ends. Then the next EXFC file command 
will be executed- 



ma 






■ 
I—* 







. 



* 



Hovevrr, if o program is RUNning while an EXEC file is OPEN, any INPUT 
statement in the program will take the next field in the file being EXECed 
as Its response, ignoring the keyboard. Worse yet, if that response Is an 
immediate-execution DOS command, the command will be executed before the 
program continues. Results can be very confusing. 



$ 



If you Interrupt a RUNning Applesoft program by typing CTRL-C while an 
EXEC file is OPEN, the remainder of the EXEC file will usually not be 
executed* 

If any field of an EXEC file cannot be interpreted as a valid BASIC 
command or program line, the message 
SYNTAX ERROR 

la generated, and the next field is read into the Apple. Thus, you can 
EXEC any text file, whether or not it contains BASIC statements (first 
be sure you've SAVEd any program in memory). In HON C t I, mode, this 
can provide a crude but handy tool for quickly examining the contents of a 
text file. 

The EXEC command can also be used with the Relative-field position 
parameter, in a way that is a bit different from POSITION'S use of that 
parameter. The syntax for this use is 
EXEC f [,Rpl 

where Rp specifies that file f is to be EXEC'd starting in the p-th field 
of file f. Since EXEC always sets the poaition-in-the-file pointer to the 
first character of the file, so the parameter Rp always indicates the p-th 
field relative to the file's beginning . Thus p always corresponds to 
the file's actual , or absolute, field. R0 indicates that EXECing begins 
with the file's first field, Rl indicates EXECing begins with the second 
field, etc. 



& 



Note that this is different from POSITION'S use of the R parameter, 
where I \ is a relative field only, and may indicate different actual 

program. 



file fields at different times in a 



$ 



EXEC MYFILE, 
generates an 



Rf 



OF DATA 
message if the R parameter specifies 
end* (If the first field beyond the file's 
happens). 



the second field beyond the file" 
end is specified, nothing 



78 






79 



CHAPTER 8 



RANDOM-ACCESS FILES 
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Mndoo-Acc«*ft nun hcv m*T 

A Specific Ucoti 

KulClpL« Accord* 

A timmooMttrntlaal The RANDOM PTograa 

tfHITEiD. and l£ADlnj R*ndow-Acc<*« File« 





For a better understanding of the information presented in this chapter, 
it ia suggested that you first read Chapter 6, on Sequential filed- 

RANDOM-ACCESS FILES: HOW THEY WORK 

Rnndom-accesa text fllea are like a collection of equal-sited cells in a 
honeycomb — some cells My be full, others may be empty. Each "cell" is 
called a record . When you create a random-access file, you must specify 
the standard site for the records the file is to contain. 

Dnlike the fields in sequential files, which may be of almost any length, 
the records in a random-access file are of specified fixed length. The 
first time you WRITE to any particular record in a file, enough space is 
set aside on the diskette for a complete, standard-length record, whather 
or not the record is actually filled. So random-access files don't 
necessarily represent an efficient use of space. However, since these 
files are set up io such a regular fashion, it's fast and easy to retrieve 
or modify information from any part of the file « hence the name 
"random-access" flit* 

Random-access files should be used in applications requiring fast access 
to various parts of the file, or where individual pieces of information in 
the file need to be changed fairly often. For example, a random-access 
fila is particularly suitable for maintaining a trailing list. 

Random-access files ore created and retrieved in a manner very similar to 
that used for sequential files. The main difference is that certain 
commands have additional parameters: OPEN requires an L {Length of record) 
parameter, while READ and WRITE each use an R (Record number) parameter. 
Some sample programs will be presented and discussed before getting into 
details on creating and retrieving random-access files and how the new 
parameters work. More technical information about random-access text 
files may be found In Appendix C* 



A SPECIFIC RECORD 



How can you access a specific record In a random-access file? The 
following pair of Applesoft programs illustrates how DOS allows you to 
this. The first program requests a name (N5). a telephone number (P5) 
a zip code <Z9>. then sends them to record 1 of a file called MAILER: 



do 

and 



10 

M 

:o 

40 

5© 

rt 



hot make MAILER 

M - CHR* C*>: «*H CTRL-D 

input -name: " >m 

INPUT -PHONE: "> P* 

INPUT "ZIP CODE: "-» 
PRINT f>«. "OPEN HMU31. 
PRINT Of . "WRITE PilltSI 
PRINT Ht: PRINT P* PRINT 
PRINT D«> "CLOSE MAILER" 



■mV 



n i 



Ha 





± 



ft? 3 



I. hi.- 20 places a CTRL-D in the variable DS, as usual. 

Lltlaw 10 through 50 request the information to be stored. 

Do not type any commas or colons in your responses. 

Llna h0 OPEHs a file called KAILER, with 200-byto long records. 

Line 70 prepares for recording information in record 1. 

Line fl0 sends NS, FS and ZS to the diskette -- since record I was 
specified in line 70, all three pieces of information 
are recorded in record I, separated by RETURNS. 

Mm- 90 CLOSES the file. 



With HON C, I, in effect, when the program is RUN you'll see: 

WW* AMY DOAKS 

PHONE <4ZS) 535-1010 

IP CODE $3014 
OPEN MAIl£R,L2«» 
URITE NAILER. Rl 

amy oowks 

% 425.1 559-1019 
«««4 

•»SE MAILER 

Record 1 of the file MAILER can be retrieved by this program: 



10 REN RETRIEVE NAILER A 

20 C*» - CHR« <4>: REM CT*1_-|> 

3» PRINT OftVOPEN WILER, -.2*0' 

40 PRINT S>9i-KPt> NAILER, Rl" 

30 INPUT N1*,P1».Z1« 

70 PRINT £*; -CLOSE MAILER' 



Uhen RUN with HON C, I, 0, you'll see the following- As usual, the pair 
of question marks Indicates an INPUT with more than one response. 

OPEN MAILER. Liflft 
HEAT' NAILER, Rl 
*%HV DOAKS 
??<4») 555-1010 
^■95014 

1SE MAILER 

And here is a slightly different program to retrieve record 1 of MAILER. 

1U REM RETRIEVE NAILER. B 
MM* — REM QUOTES CONTAIN 
CTRL-O 
" PRINT M; -OPEN MAILER, l^O*" 
40 PRINT Mi "READ MAILER. Rl" 
W INPUT Nl« 
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6* INPUT Pi* 

?* INPUT S\> 

90 PRINT D«- -CLtfSC HBIL£R* 

w two 



MUtTIPLE RECORDS 

The program that created the random-access file MAILER wrote to a single 
record In the file, saving three different pieces of Information separated 
by BETURNs. TTie neat program demonstrates vrlting to several records: In 
particular, record numbers 12 through 15 of a random-access file called 
RA-FILE. 

5 REH NHKE RrVflUc 

19 f>» - 0*« i4> REN CTRL-© 

29 PRINT 0», -OPtN RW-FKE" 

30 PRINT W; "CCUTTC RH-^ItE- 

«• PRINt Wi-tTCN ftft-FItE. LM' 

3# FCT? I - 12 TO IS 

69 PRINT f»;"MRIT£ RPr-FlL£, «'. I 

79 PRINT -NNNE flCCMESS "j I 

99 NEKT I 

M PRINT f»; "WRITE Mft-F1L£. R15* 

1M PRINT -DOS" 

119 PRINT X>»> "CLOSE R»-*IU" 

Line 10 sets DS to CTRL-D. 

Lines 20 and 30 make sure RA-FILE Is a new file 

Line 40 OPENa the file RA-FILE. whose records will each b« 

30 bytes in length. 
Lines 50 through 80 create a loop that URITEs the information 

NAME ADDRESS 

followed by the record number, for records 12 through 15 

Note that you oust specify each record In a new WRITE 

command, before having PRINT send characters to that 

record. 
Lines 90 and 100 change the information in record 13 to the 

text given in line 100's PRINT command. 
Line 110 CLOSES the random-access file RA-FILE. 



If HON C,I,0 is in effect when the program is RUN, you'll 
following: 

OPfN RR-PH ( 

;>i.l n m -r !: r 

'«fcU RA-FILE* L3« 

NP1TF Rfi-FILE. R32 

S>m( flpMCSS 12 

MRJTf RA-F1LC* R13 

nmme nwRess 13 

HI Iff Rft-PILE- Rl« 
*<H*k HftAESS 14 
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see the 






i 

mTJU 



MRlTt fr» # ILK I 

w»* time. 



fashion, you can READ information from a selected 
text ile. The next program retrieves records 12 



In a similar 

records of n 

of the file called RA-FILE, trying, on line 60, to find which 

contains the letters "DOS" as the first thro* characters. 



record or 
through 15 
record(s) 



5 ffEW RCTRieVE Rfl-FILE 

t€l &• = O*** C4>: REM CTHU-0 
-» PftlNT !>».. *OP€N Rft-FILEj L2»* 

39 Ft* J « 12 TO 15 

60 IP LEFT* CflfcJ) * -COS* THEN 
PRIWT -»CCO«t> "■ -J." WRS CHR 
NQED ■ 

re NtXT r 

BO PWZNT &•/ "CLOSE W»-flL£- 

Line 10 sets up CTRL-D in D$« 

Line 20 OPEHs the text file RA-FILE, whose records are 30-bytea 
long (that's what we specified when the file was 
created In an earlier program, remember?)* 

Lines 30 through 70 READ records 12 through 15 of RA-FILE. 

Note that you must specify each record in a new READ 
command, before a subsequent INPUT will read characters 
from that record. In line 50, each record cones in from 
the disk as an ASCII String terminated by a RETURN* 
Line 60 checks the 3 leftmost characters of the INPUT 
string AS from record r, to see if the word 
there. If it is f the message "RECORD r WAS 
Is printed and the search continues. 

Line 80 closes the file. 



"DOS" is 
CHANGED-" 



Here's what 


you'll see when yon 


effect: 






OPEN 


Rtt-^ILC 


L.3P 


REflfc 


R«-fIL£. 


R12 


fJFME 


RGDRESS 


K 


*EHb 


RW-PILE. 


■ 


-'I'OS. 






RECORD 13 WHS 


CH«MGfct> 


««P 


F**-FILt 


R14 


•aflPJE 


*ODRi 


M 


RtflD 


^-PIL£. 


R15 


'wnw 


»«X>« 


IS 


ex 


R*»-F | 





RUN the program, if MOT C, I f is in 
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Notice that when the file was retrieved only records that had been written 

to were examined. If you had asked for record 8 In RA-FILE, you would 

have received the 

END OK DATA 

MStaB** since no Information had been written to that record of the file. 

Similarly, had you tried to INPUT more than one field from any of the 
existing records you would have been given the Bame message: each of 
records 12 through 15 contains only one field* 



A DEMONSTRATION: THE RANDOM PROGRAM 

Last but by no means least, the System Master diskette contains a program 
called RANDOM that uses a random-access text file to demonstrate a small 
inventory control scheme. And by small we mean small: the program can 
handle at most 9 parts. This keeps the program simple. The Apple, of 
course, Is capable of handling thousands of parts in an inventory. 



First the program copies itself and the random-access text file APPLE 
PROMS used to keep track of the inventory, then it automatically RUNr the 
program for you- You can list one or all items in the inventory. You can 
also change items, either one at a time or all at once. Here's how it 
works. Remember to press the RETURN key each time you complete a 
response. 

1) Prom the System Master, 
RUN RANDOM 

and you should see the message 

THIS PCH0NSTO4T1ON WILL NOT EXECUTE ON 
> ^JTE-MTOTEi T*f> DISKETTE SUCH ftS 
VOtR 005 SV6TFJ1 fWSTB-2 

FOR VOUR CONVEWEMCe, PKQVlStGK* H«V6 
BEE** nftt* TO COPV WIS PROGI»»! AND IT'S 

data to monmx diskette. 

OO VOU MISH TO CO THIS MOM? <V Oft N> V 

I£ you type N Eor "no" In response to the above message, 
you'll find yourself back In Applesoft* 

2) Press Y FOR "yes". You'll see the message 

WW REAPING OATft 
Followed by the message 

INSERT AN IMJTIALIZEP DISKETTE* THEW 
F*ESS THE RETURN «£V TO PEOFN TftflMSFER 

3) Resove the System Master diskette, and place a 
non-write-protected diskette In the drive, then press 
the RETURN key. You'll perhaps catch a glimpse of 
the message 



3" 
3* 

& 
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T 



IMEft H* PMX*t»1 lW" DATA HAVE BEEN 
Fil.LV TfrXN " r- r*E i-rograa NILL 

kuiM running 

and then the program will begin execution. 



4) Nov you should see this? 

".wiw n NP 



.... necR 



LIST 1 

CHANGE 2 

EXIT 2 

CHOOSE NUHPER U - J> 1 

Press 1 and you should see this message: 

PART NUMBER 1-9 <e-ALL> o 

5> Press 0, to get a list of all "parts" in this "inventory 
system" and you'll see 



SI3E 



— — 




236 


see 


756 


1250 


2S€ 


e 


236 


■ 


2SE 


•»ji 


256 


468 
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512 


741 


ZS6 





PARTS NHHE 

1 PARALLEL PRINT 

2 COAWUNI CATIONS 

3 'JOT AVAlLABLE> 

4 CNOT available:* 

5 PISK BOOT 
STATE MACHINE 
SERIAL PRINTER1 

6 SERIAL PRINTERS 



PRESS THE RETURN KEV TO CONTINUE 

When you're ready to return to the list of options, press 
the RETURN key. 

6) Try out the various program option*!. Choice 1 allows you 
to Itet parts by part number, one at a time, as well as 
all at once. 

Choice 2 allows you to change any or all part names and 
descriptions. For example, suppose part 3 should be 
named COSMIC GLUE, size 56, with 1234 In stock. Here's 
how to revise the entry for part 3: 

select option 2, CHANGE 

select part number 3 

the old part name is displayed, with the cursor at its 
start, to allow you to enter the new name; when you 
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press the RETURN key the cursor will move to the right 
and perform similarly (or part size and quantity 
to uttc the currently existing name or size or quantity, 
just press the RETURN key by itself. 

Choice 3 will stop the program. 



WRITE-ING AND RE AD-ING RANDOM-ACCESS TEXT FILES 

When used with random-access files, the CLOSE command works exactly as It 
dOH with sequential files (see "OPENing and CLOSElng Sequential Files" in 
Chapter 6). However, the syntax for OPEN has an additional parameter, the 
L parameter, which is required . 

OPEN f ,Lj USs] [»Dd] [,Vv] 

The "L" stands for "Length-of-record"; the number j Indicates how many 
bytes (characters and digits) are to be allotted to each record In the 
random-access file you're creating (or, if you're retrieving a file, the 
number that were allotted when the file was created). If the L option is 
omitted, j is assigned the default value of 1. The number ] oust be In 
the range 1 through 32767. 



$ 



When you 
parameter 
file, DOS 
positions 
document a 
programme 
to always 
names as 
RAND FILES 
STOCKLIST 
DIRECTOR! 
There Is 
you must 



OPEN a file prior to READing , if you specify a different Length 
, than you specified when you OPENed prior to WRITEinft the 
will blindly use the new Length parameter to calculate record 
within the file. You will have to keep detailed written 
tion on the structure and contents of your files (some 
rs keep such information in record of the file). It's helpful 
include the Length parameter In each file's name , with such 

:L20 

S-LI00 

ES(L50) 

no way to find the length of a record in a random-access file: 

make this information part of your documentation. 



* ! 3 




±a 




Records should never be longer than the number of bytes specified by the I. 
parameter; records may be partially over-written or combined with 
confusing results- 






WRITE and READ each have an R parameter* to be used when 
retrieving particular records in random-access files- 



creating or 



i i 



WRITE f 
READ f 



LRr] 
lt*rl 



Examples: WRITE LEGIBLY, R3> 
READ FA5T t R13 



**a 
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J. 



Tlu* Hr (Record) parameter is used to create (with WRITE) or retrieve 
(with READ) the rth record of the file. The default value of r is 0, 
specifying the first record of a file. 



x 



Using CTRL-C to stop a READ in Applesoft causes 
generated : press the RESET key instead. 



a string of REENTERS to be 



In some respects, each separate record in a random-access text file may be 
treated as a short sequential file. WRITE and READ can be used with a 
Byte parameter in addition to their R parameter. The Byte parameter 
specifics the beginning byte of the specified record, for the next PRINT 
(after WRITE) or INPUT or GET (after READ). 

WRITE f (,Rrl |,Bb] 
READ f (,Rr] [,Bb] 

If specified, .the B (Byte) parameter causes WRITElng (or READlng) to 
begin nt the b-th byte of the specified record. The default value of b is 
0, the first byte of a record. The B parameter may specify a position in 
the record either before or after the current posltlon-ln-the-f lie 
pointer. Using the B parameter necessitates a thorough, detailed, 
byte-by-byte knowledge of the contents of each record in the file. 

Once READ or WRITE has moved the poaltion-in-thc-f He pointer to a 
particular record, POSITION can also be used to move the pointer ahead 
(only) to further relative-field positions within the record. However, 
POSITION cancels either WRITE or READ mode (without changing the 
posUion-in-the-file pointer), so another WRITE or READ command (this time 
with no parameter) is necessary to re-instate that mode. 

Details on how information is stored on the diskette in general, and In 
random-access files in particular, may be found in Appendix C. 
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CHAPTER 9 



FILES 



ACHINE LANGUAGE 



92 ttachlTM Ura|MK« Pllu 

92 BSAVR 

91 fcLOtt 

#3 M» 

9* Ttw BHTS 4obr«ittM 
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MACHINE LANGUAGE FILES 

DOS allows you to store on diskette, and retrieve from diskette, the 
information in your Apple II** memory. You have already seen the DOS 
commands SAVE, LOAD and RUN: these commands deal with the contents of 
Apple s program memory, interpreted as commands in BASIC programs. The 
DOS commands discussed in this chapter -- BSAVE, BLOAD and BRUN — perform 
similar functions, but they deal with the contents of an^ portion of 
Apple'* memory, in its uninterpreted, raw binary-and-hexadecimal form. 



The B before each of the following commands stands for a Binary file; a 
B also precedes the name of binary files in the CATALOG. "~A binary file 
Just an exact, bit-for-bit copy of the information that was stored in a 
specified range of Apple memory locations. Those locations may have 
contained a machine-language program, binary data, or a bit-mapped 
picture" from Apple's high-resolution graphics screen. 



Is 



BSAVE 



The BSAVE command creates a file named f and stores all the contents of a 

segment of memory. The syntax is 

BSAVE f ,Aa, Lj [,Gs] [»Dd] (,Vv] 

where as usual the S, D, and V parameters stand for 

number, and volume number. Note that the A and L pt 

optional. 



slot number, 

rameters are 



drive 

not 



The A parameter specifies the starting Address (in either decimal or 
hexadecimal code) of the memory portion to be stored on diskette. A 
dollar sign ( S ) must precede an address expressed in hexadecimal. If 
the A parameter is less than or greater than 65535, a 
SYNTAX ERROR 

message is displayed. Therefore, equivalent negative addresses may not 
be used with this command. Within the range through 65535, no error 
message is generated if the A parameter specifies a starting memory 
address that does not correspond to actual. Installed memory chips. In 
practice, it is not useful to specify an A parameter greater than the 
maximum memory address in your Apple (49151 or SBFFF on a 48K system). 

The L parameter specifies the Length, in bytes, of the memory portion to 
be stored. If the L parameter is less than or greater than 65535, a 
SYNTAX ERROR 

message is generated. If the L parameter is or in the range 32768 
through 65535, a 
RANGE ERROR 

message is generated. 32767 i* the greatest number of bytes that can be 
stored in a single field on the diskette. If you wish to store more than 
32767 memory locations, use two BSAVEs. Within the range 1 through 32767, 
no error message is generated if the L parameter specifies a range of 
memory addresses, not all of which correspond to actual, installed memory 
chip. In practice, it is not useful to specify a range of memory 
addresses extending beyond the maximum memory address in your Apple (49151 
or SBFFF on a 48K system). 
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Them* examples each create a file named PICTURE containing an Image of the 
second hlRh-resolution graphics area of the Apple's memory. They are 
operationally identical, but their starting address and length parameters 
are given in different forms. 

BSAVB PICTURE, AS40O0, L$2«a 

BSAVE PICTURE, A16384, L8192 

BSAVE PICTURE, A16384, L$2000 

BSAVE PICTURE, A$4000, L8192 



BLOAD 

The BLOAD command returns the contents of a Binary file to your Apple II's 
memory. BLOAD does not erase a BASIC program in memory, unless the data 
Is BLOADed into the particular portion of memory containing your program. 

The syntax is 

BLOAD f f.Aal [,Ss] (,Dd) [,Vv] 

where the S, D, and V parameters are as usual. If the A parameter is 

used, then the Binary file's contents replace a portion of the existing 

contents of Apple's memory, beginning at address a* If the A parameter is 

not used, the file's contents are returned to the same Apple memory 

locations whose contents were originally BSAVEd. See BSAVE for a complete 

discussion of the A parameter. 

Assume the binary file PICTURE contains a high-resolution picture. Either 

of these examples places the picture into the first high-resolution 

graphics area of the Apple's memory: 

BLOAD PICTURE, A8192 

BLOAD PICTURE, A$2000 

Either example also clobbers the RAH version of Applesoft. 

Note : a machine-language program may no longer be executable 

if it is moved to a memory location different than the 
one from which it was saved- 



BRUN 



The syntax of the 
BRUN f [.At] (,S«: 
The Binary file f 



BRUN command is the same as for BLOAD: 

[,Ddl I,Vv] 
should be a machine-language program. 



First BRUN does a BLOAD. If the A parameter is given, the file's contents 
are placed into Apple's memory beginning at location a. If the A 
parameter is not used, the file's contents are returned to the same Apple 
memory locations whose contents were originally BSAVEd. See BSAVE for a 
complete discussion of the A parameter- 
After BLOAD in g the file, BRUN does a machine language jump (JHP) to 
location a. If the file was a machine-language program, this begins 
execution of that program. 
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THE RWTS SUBROUTINE 

Normally, user access to and from the DISK II is restricted to the us* of 
DOS. However, another method of Accessing the DISK II Is available to 
KchlM language programmers. You may skip this section If you're not 
familiar with machine language* 

The DISK t can be accessed directly from machine language throuch the use 
of the RWTS subroutine, which is part of the DOS- The "RWTS" stands for 
"Read or Write a Track and Sector". In the following explanation, any 
nunfcors preceeded by S are hexadecimal numbers* 

Every diskette Initialized by the DISK II drive is separated into 35 
tracks, numbered to 34. These tracks may be thought of as grooves on a 
phonograph record, except that they are not connected with each other- 
Basically, the tracks are arranged in separate concentric circles, with 
the large hole in the center of the diskette forming the common center of 
the circles- Track is on the outer edge of the diskette, while track 34 
Is nearest the center* The disk drive has a "head" that acts very nuch 
like the needle on a record player, except that the head on the disk drive 
is magnetic- This head coves to different tracks on the diskette, where 

it either reads Information off of the diskette, or writes information 
onto the diskette* 

Each track on the diskette consists of 16 sectors* Sectors are pre-defined 
groupings on each track, that allow the user to work with single blocks of 
2*6 bytes, rather than with the entire 4096 bytes that fit on one track. 
The sectors within a track are individually numbered, consecutively, to 
15 around the diskette. As the diskette spins, each sector will pass 
underneath the head, at which time the head may write to or read from that 
sector. Each sector consists of two portions: the address field and the 
data field. The addres field contains information concerning which track 
the head is on, which sector is about to spin past the head, and the 
volume number of the diskette. The data field contains an encrypted form 
of the actual 256 bytes of data which were stored on that sector* 

The "Read or Write a Track and Sector" subroutine (referred to as the RWTS 
subroutine)* allows the user to write information to, or read information 
from, any track and sector on the diskette, via machine language* In order 
to use the RVTS subroutine, the user must first create an IOB 
(Input/Output control Block) table, and an accompanying "Device 
Characteristics Table". The IOB tells the RWTS subroutine which slot and 

d T 1V j ""■*" the dlsk drive will be In, which volume nuofoer to expect on 
the diskette, which track and sector to access, and whether to read from 
or write to the diskette. The Device Characteristics Table provides some 
Information to the RWTS subroutine that is necessary to operate the Apple 
DISK II, 

To use the RWTS subroutine, the user must set up the IOB and the Device 

Characteristics Table somewhere In memory* A "controlling subroutine" must 
be written and stored in memory. The subroutine must JSR to the starting 
address of the RWTS subroutine (at location S3D9). When the ROTS 
subroutine is jumped to, the A and Y registers must contain the address of 
the starting location of the IOB. The A register must contain the high 
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i 

=3 



address byte, and the Y register the low address byte. The 
IOB is given in Table 3, at the end of this section. Table 
i r ,.i of the Device Characteristics Table. 



format of the 
4 gives the 



Mere Is an example of how to use the RWTS subroutine. The sample IOB, 
Device Characteristics Tables, and a controlling subroutine will all be 
loaded Into memory Just after location SC00. 



The f ol lowing controlling subroutine 
the address of the starting location 
subroutine* 



will load the A 
of the IOB, and 



and Y registers with 
ttien jump to the RWTS 



$<:00- 


A9 0C 


LDA 


#S0C 


Load 


SC02- 


A0 0A 


LDY 


*S0A 


Load 


SC04- 


20 D9 03 


JSR 


S03D9 


Jump 


SC07- 


60 


BTS 






SC0H- 


00 


BRK 







A register with $0C 
Y register with $0A 
to the RWTS subroutine 



The following IOB is one that you would use to access slot 6> drive 1 
write 256 bytes of memory starting at location $2000, onto track 18, 
sector 6 of the diskette: 



Purpose 

IOB type Indicator, must be S01 

Slot number times 16 

Disk drive number 

Expected volume number 

Track number 

Sector number 

Low-order byte of Device Characteristics Table 

High-order byte of Device Characteristics Table 

Low-order byte of data buffer starting address 

High-order byte of data buffer starting address 

Unused 

Unused 

Command code, $02 - write 

Error Code 

Actual volume number 

Previous slot number accessed 

Previous drive number accessed 



to 



Lor.it ion 


Code 


$C0A 


0T" 


SC0B 


60 


SC0C 


01 


SC0D 


n 


SC0E 


12 


SC0F 


06 


SC10 


20 


sen 


0C 


SC12 


n 


SC13 


20 


scu 


m 


SC15 


00 


SC16 


02 


SCI 7 


00 


SC18 


00 


SC19 


60 


SCI A 


01 



The following Device Characteristics Table must be Included, 
it at location $C20, just after the IOB. Locations $C10 and 
IOB above point to the address of the Device Characteristics 
starting location* 



Device type code (put a $00 here) 

Number of phases per track (put a $01 here) 

Time count (put a $EF here) 

Time count (put a $D8 here) 



we'll place 
$CI1 in the 
Table's 



Location 


Codo 


SC20 


00 


SC21 


01 


SC22 


EF 


$C23 


D8 
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When you have loaded the 10B at $C0A, the Device Characteristics Table at 
$C20 f and the controlling subroutine to load the A and Y registers at $C00, 
then 

cMc 

or 

CALL 3072 

will cause the entire routine to execute* 



TABLE 3: FORMAT OF IOB 



Bytel 

I 



Name Purpose 

IBTYPE Tells the RUTS subroutine what type of IOB this 
is* Should be a $01. No other type codes are 
currently defined* 

IBSLOT Must contain the number of the slot times 16, 
in which the disk drive's controller card is 
located. For example, if you want to access 
slot #6, the value $60 must be stored in this 
location* 

IBDRVN Must contain the number of the disk drive to be 
accessed — either $01 or $02* 



IBVOL 



The volume number of the diskette to be 

accessed must be stored here* Volune $00 will 

number assigned to any 



ms 


'* 




* A 


* 3 


* 3 


ff 3 


■ta 





mm: 



i * 



oatch the volume 
diskette. 



768 



LBTKK 



IBSKCT 



IBDCTP 



The number of the track 
accessed Is stored here* 
range $00 to $22. 

The number of the sector 
accessed is stored here* 
rangc $00 to $0F. 



to 34) to be 
Must be within the 

(0 to 15) to be 
Must be within the 






9M0 



IBBUFP 



These two bytes must contain the address of the 

starting location of the Device Characteristics 
Table (see below). Byte 7 must contain the 
low-order byte of the address* and byte 8 must 
contain the high-order byte- 
Bytes 9 and 10 must contain the address of the 
starting location of the "data buffer". The 
data buffer is a 256-byte long section of 

memory upon which the RWTS subroutine will 
operate. If you are writing onto the diskette, 
the information in the data buffer will be 
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B Si 



is 



written onto the diskette. If you are reading 
from the diskette, the information that conies 
off of the disk will be stored in memory at the 
location of the data buffer. 256 bytes is both 
the minimum and the maximum amount of inform- 
ation that can be read or written by the RWTS 
subroutine* 

Unused 

IBCMD In this byte is stored the command code that 
tells the RUTS subroutine exactly what to do. 
The values that can be stored in byte 13 are: 
$00 — Null command . Does nothing but start 

the disk drive and position the head. 
$01 — Read the entire 256 bytes stored on the 
diskette at the specified track and sector, 
and store thea in memory at the location of 
the data buffer. 
$92 — Write the next 256 bytes stored in 

memory at the location of the data buffer on 
to the diskette at the specified track and 
sector. 
$0i — Format the diskette. When a diskette is 
formatted, self-synchronizing nibbles are 
written on every track and sector on the 
diskette. Because all of the diskette is 
formatted, the values in bytes 5 and 6 are 
ignored. All of a formatted diskette is 
available for use; there is no DOS, or 
anything stored on the diskette until the 
user puts something there. 

IBSTAT This location will contain the code number for 
any error that may be encountered during 
execution. If the RWTS subroutine returns with 
the carry flag clear, no error has occurred. 
If it returns with the carry flag set, this 
byte indicates what type of error has occurred. 
$10 — Diskette is write-protected, and cannot 

be written to. 
$20 — Volume mismatch error. The volume 

number of the diskette found was different 
than the volume specified in byte 4* 
$40 — Drive error. Something unusual is 

happening. 
$80 — Read error. The RWTS routine was, after 
48 repeated attempts, unable to read either 
the address field or the data field. If the 
data field for the specified sector has 
nsver had anything written on it, then a 
read error will result, because there is 
nothing to read. 

TBSMOD The volume number of the diskette that is 

actually found will be stored in this location* 
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TABU* J; FURMAT OF 10B 1 continued ) 
Hytt!* Name Purpose 



16 



IOBPSH 



17 



IORPDN 



This byte must contain the sloe number tines 16 

of the slot that was accessed most recently. 

For example. If you previously accessed a disk 
drive In slot 5, store the value $50 here. If 

there is no controller in the specified slot, 
the disk will hang* 






CMAPTIBIO 



PUT, AND CHAINING 



1M falsctini I/O BovU*s: W#. F*l t ttri Oth«r Stnff 
l»b Kat*t*r fcUK OUXV 



This byte must 
drive that was 
or 502. 



contain the number of the disk 
accessed most recently — * a $01 



Table 4: FORMAT OF DEVICE CHARACTERISTICS TABLE 

Byte! Name Purpose 

1 DBVTPC Device type code, telling what type of device 

this it. A $00 should be stored In this byte 
for use with a DISK II. 

2 PPTC A $01 should be stored here. 

3&4 HOHTC Hotor on tine count complemented, in 100 

micro-second intervals* A SEP should be In 
byte 3» and a $D8 In byte 6, for use with a 
DISK II 
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SELECTING I/O DEVICES: IN#, PR# AND OTHER STUFF 

There are various ways In which information can be used as input or output 
for your Apple computer- Very often the keyboard serves as a source of 
input* Usually the Apple uses a TV screen for output, but any accessory 
or peripheral connected to a controller In one of the seven Apple 
accessory slots can be used for input or output using the IN* and PRJ 
command**. 



i; 



Kxampltf 
IN* 6 



IN* 



PR* 1 



PR$ 



obtains subsequent Input from the device controlled from 

slot *6. Note: if slot 16 contains a disk controller 

card, this command will cause DOS to be booted* If no 

device is in slot *6, the system may "hang". Press the 

RESET key to recover. 

obtains subsequent input from the keyboard (not slot #0), 

instead of a peripheral device* 

transfers output to the device controlled from slot 

usually the printer* Note: if no device controller 



1, 



card is installed in slot 
and you'll have to press 
returns output to the TV 



01> the system may "hang" 
the RESET key to recover, 
screen (not to slot *0). 



The syntax for the commands is 

IN* s 

or 

PR* s 

where s specifies the slot to use. What happens depends on s: 



value of a 
less than 
I 

1 through 7 

8 through 16 

17 through 65535 
greater than 65535 



result 



SYNTAX ERROR 



re-establishes usual device (for INI, input from 
the keyboard, for PR*, output to the TV screen) 

transfers to device controlled from the specified 
slot (boots DOS If a disk controller card is in 
that slot) 

SYNTAX ERROR in deferred-execution mode ; 
the system hangs in Immediate-execution oode 

RANGE ERROR 

SYNTAX ERROR 



m 
m 

i 



The command IN? re-establishes input from the keyboard; PR* 
re-establishes output to the TV screen. 






With DOS in effect, the IN* 
execution mode in the usual 



and PR* commands may be used in immediate 
way (see your BASIC manuals). But when they 
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B 



I 



3 

3 
3 
3 
H 
3 

3 
3 

3 
3 
3 
3 

3 
3 

3 
3 
3 
3 



are Ismied by linen In a program, IN* and PRf must take the form of DOS 
( oimanndn wurh as 

II* l>S - "": KKH CTRL-D 

29 PRIKT l>$; "PR* I" 

10 PRINT DS; "IK* 2" 



When DOS is not in effect, the IN* 
*»o Apple Honitor Input and Output 
and output devices* 



and PR* commands set the contents of 
registers to select the desired input 



Mien DOS in in effect, the contents of the Apple Monitor Input and 
Output registers are set to select DOS, while the contents of the DOS 

Input and Output registers are set to select the desired input and output 
devices* The following paragraphs describe what happens each time a 

character leaves or enters the Apple* 

When the Apple sends an output character, the Apple Monitor Output 
register directs that character to DOS* If the character is to be sent on 
(because it is not part of a DOS command), DOS does a fast two-stage 
switch: 

1. First, DOS replaces the contents of the Apple Monitor 
Input and Output registers with the contents of the DOS 
Input and Output registers. Then it sends the character 
out to the device now selected by the contents of the 
Apple Monitor Input and Output registers* 

2. Next, DOS re-connects Itself by again placing the 
pointers to DOS in the Apple Input and Output registers. 



Similarly, each time the Apple asks 
Monitor Input register directs that 
does its fast two-stage switch: 



for an input character, the Apple 
request to the DOS. Once again, DOS 



1. 



First, DOS replaces the contents of the Apple Monitor 
Input and Output registers with the contents of the DOS 
Input and Output registers. Then it obtains an input 
character from the device now selected by the Apple 
Monitor Input and Output registers. 



2, 



Next, DOS re-connects itself by ag; 
pointers to DOS in the Apple Input 



iln placing the 

and Output registers. 



When DOS is in effect, DOS Intercepts all input characters from the input 
device before they reach Applesoft or Integer BASIC or the Monitor. That 
is why IN* and PR*, when typed on the keyboard as immediate-execution 
commands, can be trapped and used by DOS to change the DOS Input and 
Output registers. 

Similarly, DOS Intercepts all output characters from the Apple before they 
reach the output device (but after they have affected the Apple Monitor 
Input and Output registers). That is why IN* and PR*, If Issued from 
within a program but not in PRINTed DOS commands, can disconnect DOS by 
changing the Apple Honitor Input and Output registers before the commands 
ever get to DOS. Because the entire contents of the Apple Monitor Input 
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and Output registers are replaced each time DOS attempts to send or 
receive a character* DOS will usually re-connect Itself If It was not 
disconnected at both Input and Output registers simultaneously. 



© 



If you execute a PR# command from within a program, with a program line 

such as 

50 PR* 1 

then DOS will be partially disconnected and unable to intercept subsequent 

output* DOS Is still connected for input, and the next attempt to obtain 

any input character will cause DOS to re-connect itself for both input and 

output* 

The same situation occurs with the use of IN* inside programs when DOS is 
In effect. A program line such as 
60 IN* 1 

will disconnect DOS for subsequent input. DOS is still connected for 
output* and the next attempt to send out a character (even a return or a 
prompt character) will cause DOS to re-connect Itself for both input and 

such conflicts and allow DOS to manage the Input and 
issue PR* and IN* commands in immediate-execution mode, 

such ae those mentioned earlier: 



output 
Output 



To avoid 
registers. 



or as DOS commands in program lines 
10 DS - "": REM CTRL-D 
20 PRINT DS; "PR* 1" 
30 PRINT DJ; "IN* 2" 



The CTRL-D character tells DOS that the following output characters are a 
DOS cc 
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E 
E 



V 



TAM.K I: APPLE HON I TOR INPUT AND OUTPUT REGISTERS 



Monitor Input Rcginter: Locations 56-57 ($38-539) 



When Register 

contents 

arc set by 



To the 
value 



RESET -741 

CTRL-K [Note I] ($FD1B) 
INtfJ [Note 2] 



Then subsequent input 
cooes from 

Honitor Input Routine 
from Apple keyboard 



s CTRL-K [Note I) 49152 * s*256 Slot #s 

INfs (Note 2) (SCs00) If slot *s contains disk 

[ where s>() ) controller, then boot DOS 



DOS boot 



-8574 + Top of win. DOS 

(-S2I7E + STop of menu) 



Monitor Output Register: Locations 54-55 ($36-537) 



When Register 






contents 


To the 


Then subsequent output 


are set by 


value 


floes to 



RESET -528 

9 CTRL-P [Note 1] (SFDF(I) 
PR10 [Note 2) 



s CTKL-P INote I] 
[Note 2] 
where s>0 ] 



49152 + s*256 
(5C5*K) 



Honitor Output Routine 
to TV screen 



Slot ts 

If slot Is contains disk 
controller, then boot DOS 



DOS boot 



-8514 + Top of mem* 
(-S2142 + STop of mem.) 



DOS 



Note 1. The commands a CTRL-K and s CTRL-P are Honitor commands* To 

type CTRL-K (which does not appear on the TV screen)* type K while 
holding down the CTRL key. 

Note 2. When T>0S is in effect, this command will affect the contents of 
the Apple Monitor register only if the command Is issued as an instruction 
In a stored program and not in a PRINT CTRL-D instruction- 
Note 1. In addition tn the commands p^ntioned in Table I» directly 
I'OKKIng appropriate values into the Apple Honitor register locations can 
also be used tn select Input and output device , or to re-connect a 
disconnected 1>oS- 
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TABLE 2; DOS INPUT AND OUTPUT REGISTERS 



DOS Input Register 



When Register 



contents 


To the 


arc set by 


value 


DOS boot 


-741 


RESET 3D0G 


(SPD1B) 


1N#0 (Note 4) 




PRINT DS;"INff0" 




[Note S) 




_,.____,.__________- 


-—-—*.— 


IN#s (Note A) 


49152 + s*256 


PRINT DS^'INfs" 


<$Cs00) 


[Note S] 




( where s>0 ] 





Then subsequent input 
cones from 

Monitor Input Routine 
from Apple keyboard 



Slot #s 

If slot Is contains a 
disk controller* then 
reboot DOS 



later 



When Register 








contents 


To the 




Then subsequent output 


are set by 


value 
-528 




floes to 


DOS boot 


Monitor Output Routine 


RESET 3D0G 


(SFDF0) 




to the TV screen 


PRJ0 [Note 4] 








PRINT D$;"PR#0" 








[Note 5] 








PR#s (Note 4] 


69152 + s*256 


Slot #s 


PRINT D$;"PR#s" 


<$Cs00) 




If slot #s contains a 


[Note 5] 






disk controller, then 


( where s>0 ] 






reboot DOS 



3 
3 
3 






± 



Note 4. When DOS Is In effect, this command will not affect the 

contents of tin* DOS Input and Output registers if the command Is Issued as 

an Instruction In a stored program and not in a PRINT CTRL-D instruction. 

If a program line such as 

12(1 PK#3 

Is executed, the contents of the Apple Monitor Output register will be 
changed* leaving DOS partially disconnected until the next input- 

Noto S. In this command, it is assumed that the string-variable named D$ 
has been assigned the character control-D, or CTRL-D. This character, 
which does not appear on the screen, is produced by typing D while 
holding down the CTRL key. 

Note 6. No matter what input or output device is selected by the DOS 
Input and Output registers, input can also be received from the disk and 
output can be sent to the disk- 
Note J* In addition to the commands in Table II, directly POKEing the 
appropriate values into the DOS Input and Output register locations can 
also be used to select input and output devices. However, the specific 
memory locations of the DOS Input and Output registers change with 
different system memory sizes and with different versions of DOS- For 
this reason, a special procedure exists for changing the contents of the 
DOS Input and Output register locations. It is a two step procedure: 

a) Change the Apple Monitor Input and Output register 
locations to the values you wish the DOS Input and 
Output registers to contain- (This may be done by 
directly POKEing the Apple Monitor register locations 
or by executing IN# and PR< non-DOS Instructions in a 
stored program. ) 



b) CALL 1302 



(from the Monitor, you would type S3EAG). 



After this CALL, DOS will be re-connected via the Apple 
Monitor registers, and the previous concents of the Apple 
Monitor Input and Output registers will appear in the DOS 
Input and Output register locations. This CALL can also 
be used to re-connect DOS any time your program needs 
to disconnect DOS for awhile. See the program on page 
151 for an example using this technique- 
Note 8- The Monitor commands s CTRL-K or S CTRL-P , when typed on the 
keyboard, are not recognized by DOS: they affect the Apple Monitor Input 
or Output registers directly. 
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INTEGER BASIC CHAIN 

Certain applications are moat eaaily Implemented by using a series of two 
or more programs which are LOADed and RUN sequentially * In Such 
circumstances, the second program often needs to use the values of 
variables and arrays developed by the first program* The usual RUN 
command erases the first program's variables and arrays when It loads the 
necond program* In Integer BASIC (but not Applesoft) the DOS command 
CHAIN allows you to load and run a second program wl thou t erasing the 
first program's variables and arrays. 

Suppose you've been using an Integer BASIC program called PART ONE- The 

command 

CHAIN PART TVO 

will load and run the Integer BASIC program called PART TWO without 

clearing the values of any variables used in the program FART ONE* The 
CHAIN command may be issued In immediate-execution mode aa ahown above, or 
from within the last lines of the PART ONE program as a DOS command: 



20010 D$»""r REX CTRL-D 

20020 PRINT D5; "CHAIN PART TWO" 

The syntax for the command Is familiar: 
CHAIN f [ t Ss] UDdJ [,WJ 



APPLESOFT CHAIN 

The CHAIN command works only with Integer BASIC, but If you do not need to 

pass variables, it is easy to link Applesoft programs to load and run In 

sequence. In the first program. Just Include a last line such as 

20M0 PRINT CHR$(4); "RUN PART TWO" 

When this line Is executed. It will start up the second program (where the 

second program Is named PART TWO)* In the process, the first program and 

all Its variables are erased- 



A different procedure must be used In order to load and run a aeries of 
Applesoft programs without erasing earlier values of variables and arrays. 
To chain in Applesoft, you will need to use the machine-language program 
called CHAIN that is on the DOS System Master diskette. 

To chain from a program called PART ONE to a program called PART TVO, you 
must have the CHAIN program on the same diskette with the program PART TWO 
(see next page for instructions). Then, simply insert these two lines as 

the laat two lines to be executed in the PART ONE program: 

20000 PRINT CBR$(4); "BLGAD CHAIN, A520" 

20010 CALL 520' f PART TWO" 

The two lines nay use any line numbers* but they should come ooe after the 

other in the program, as indicated. The first line loads the Applesoft 
chaining ability into the computer- The second line actually does the 
chaining (but see next page, for warning). 



± 
± 
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There must be no space in the third line between the CALL address 520 

and the following quotation mark. The CALL address must not be given in 
hexadecimal. 



If you have Applesoft on the firmware ROM card, you can copy the CHAIN 
program onto another diskette by using the FID program* (Appendix J) 

If you are using RAH Applesoft (on diskette), you can copy the CHAIN 

program onto another diskette using FID (Appendix J) or as follows. First 

place the CHAIN program into Apple's memory, with the command 

BLQAD CHAIN, AI2296 

Then save it on the desired diskette, with the command 

BSAVE CHAIN, A12296, L456 



e 



Note that neither Address parameter for copying CHAIN is the 
Address parameter for actually using CHAIN- 



same as the 
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APPENDIX A 



USED WITH DOS 
COMMANDS 



tip b J UUfl UJ 

1U fty rii* Typ* 
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Unless otherwise indicated, DOS coimands nay be used either in 
immediate-execution mode or in deferred-execution node (within a program) 
However, son* text file commands (e,g. READ and WRITE) oust be used in 
deferred-execution mode. 

Most DOS commands refer to a named file. A file may be a text (data) 

file, or a program in Integer BASIC, APPLESOFT or Machine Language. The 

tables below indicate which file types may be used by each command. The 

first table lists the commands alphabetically; the second table groups 

them by associated file type. The commands CATALOG, FP, INT, MAXFILES, 

HON, NOMON, PR# and IN# are not included because they do not explicitly 
refer to named files* 



FILE TYPE USE, LISTED BY DOS COMMAND 



DOS 


Integer 


Applesoft 


Sequential 


Randon 


Machine 


Command 


BASIC 


BASIC 


Access 


Access 


Language 


Uses 


Program 


Program 


Text 


Text 


Binary 


Files: 


File 


File 


File 


File 


File 


APPEND 






X 






BLOAD 










X 


BRUN 










X 


BSAVE 










x 


CHAIN 


X 










CLOSE 






X 


X 




DELETE 


X 


x 


X 


X 


X 


EXEC 






x 






IHIT 


* 


X 








! OAD 


X 


X 








LOCK 


x 


x 


X 


X 


X 


OPEN 






x 


x 




POSITION 






X 






READ 






x 


x 




RENAME 


X 


x 


X 


X 


X 


RUN 


X 


X 








SAVE 


x 


X 








UNLOCK 


X 


x 


X 


X 


X 


VERIFY 


x 


X 


X 


X 


X 


WRITE 






X 


X 





Note: use these commands only tn deferred execution mode: 
APPEND, OPEN, POSITION, READ, WRITE 



# s 

± 



mm 

E 

E 

E 

E 

r 

■ 5) 
4* 



FILE TYPE USE, LISTED BY Fllf TYPE 



hiM-^n HA:;it ! i ] rH only 
CHAIN 



Integer BASIC or APPLESOFT files 

INIT 

LOAD 

SAVE 

RUN 



Sequential Text files only 

APPEND 

EXEC 

POSITION 



Either S equential Text Files or Random-Access Text Files 

OPEN "" 

CLOSE 

READ 

WRITE 



Hach jne Lanfttui Ee f i 1 * 
BLOAD 
BRUM 
BSAVE 



only 



All Types of Files 

DELETE 

LOCK 

UNLOCK 

RENAME 

VERIFY 



Note: these commands must be used in deferred-execution mode: 
APPEND, OPEN, POSITION, READ, WRITE 
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ff = 



e = 



APPENDIX B 



»!• 



cot 



14 OHMS GOTO Gxi« 
1(5 DiacuHlos 
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When DOS detects an error connected with disk usage, it normally displays 
n mestmgc describing the error and stops any program that Is running. 
These messages ore In addition to the usual messages generated by 
Applesoft or Integer BASIC. DOS messages can be distinguished from those 
of Applesoft or Integer BASIC as follows: 



An Applesoft mi 
7SYKTAX ERROR 
is preceded by 



ssage, such as 
a question mark. 



An Integer BASIC message, such as 

*** SYNTAX ERR 

la preceded by three asterisks. 

A DOS message, such as 

SYNTAX ERROR 

is preceded by no character at all. 



A DOS message appears exactly the same, whether you are in Applesoft, 
Integer BASIC or the Monitor at the time the message is generated. 



$ 



If a DOS message occurs when you are using the Monitor, the system Is 
reset to the type of BASIC from which you entered the Monitor. 

By using Applesoft's ONERR GOTO command <see the Applesoft manual), you 
can create Applesoft error-handling routines that deal with DOS messages 
which would normally Interrupt your program. When a DOS error occurs 
following an ONERR GOTO command in an Applesoft program, a code number for 
the type of error Is stored In decimal memory location 222. This la the 
same memory location in which Applesoft stores the code for an Applesoft 
error message. The command 
Y - PEEK(222) 

sets the value of Y to the Applesoft ONERR GOTO code corresponding to the 
error that caused an Applesoft OSERR GOTO jump to occur. 

DOS messages and their corresponding Applesoft ONERR GOTO codes are shown 
below, with the most common cause of each message. Each of the messages 
is then discussed in greater detail, with a more comprehensive list of 
causes and cures. 



ONERR GOTO CODES 



code 


DOS message 


I 


LANGUAGE NOT AVAILABLE 


2,3 


RANGE ERROR 


4 


WRITE PROTECTED 


5 


END OF DATA 


6 


FILE NOT FOUND 


7 


VOLUME MISMATCH 



Most common cause 

Applesoft not on diskette 
Command parameter too large 
Write-protect tab on diskette 
READing beyond end of text file 
File misspelled, or not on diskette 
Wrong Volume parameter 



it 

3 



2 



114 






UNKRH GOTO 
Code 



I>1>'; TTi_i;;*;_ v -i£r 



I/O ERROR 
DISK FULL 
FILE LOCKED 
SYNTAX ERROR 
NO BUFFERS AVAILABLE 
FILE TYPE MISMATCH 
PROGRAM TOO LARGE 
NOT DIRECT COMMAND 



Most common cause 



Door open, or diskette not INlTed 
Too many files on diskette 
Attempt to over-write a LOCKed file 
Bad file name, parameter, or comma 
Too many text files OPEN 
Diskette file doesn't match command 
Insufficient Apple memory aval lablc 
ind must be in a program 



DISCUSSION 

LANGUAGE NOT AVAILABLE (ONERR GOTO code - I) 

Occurs if DOS cannot find a programming language, either Integer BASIC or 
Applesoft, that is required to execute a DOS command. The commands FT. 
INT, LOAD and RUN may all Initiate a language search. If Integer BASIC Is 
requested, DOS looks for that language in ROM* If Applesoft is requested, 
DOS first looks for the language in ROM, using Applesoft from an Applesoft 
firmware ROM card (if available) regardless of the card's switch 
position. If Applesoft is not found in ROM, DOS looks on the diskette in 
the "default" disk drive — the drive indicated by the default or most 
recent values of the S and D parameters. DOS will not look on any other 
disk drive. 

This message usually arises after a DOS request for diskette Applesoft, if 
the diskette in the default drive does not contain the program APPLESOFT. 
Replace the diskette with one that contains the program APPLE50FT; or use 
the D parameter with any DOS command, to select the another drive. A 
command such as this will do nicely: 
FP, D2 



If you think DOS should have found Integer BASIC In ROM, but it didn't, 

try the following: 

Turn off your Apple and remove the cover* 

Locate the row of four large ROM chips (black, rectangular 

objects) In the middle of the main prlnted-circult board. These 

chips are labeled "ROM F8", "ROM P»", "ROM E8" and "ROM E0". 

Press down firmly on these chips. 

Replace the cover, turn on the Apple and try INT again. 



1. 

2* 



3- 

A. 



If you think DOS should have found Applesoft on your firmware ROM card, 
but it didn't, try the following: 

1. Turn off your Apple and remove the cover* 

2. Unplug the Applesoft firmware ROM card. Locate the row of 
five large ROM chips (black, rectangular objects) across the 
card. These chips are labeled I, 2, 3, 4, and 5 above 

the chips, and D0, D6, Efl, E6 and F0 below the chips. 

3. Press these chips firmly into their sockets. 

4. Plug the Applesoft card back Into slot #0, the leftmost slot. 
5* Replace the cover, turn on the Apple and try FF again. 
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RANGE ERROR (ONERR GOTO code - 2 or 3) 

Occurs when the value of a DOS command parameter or a DOS command quantity 
is too large or too snail* Refer to the manual to see which DOS commands 
are used with which parameters* 

Range 





Paramo ter 




Letter 

S 
D 
V 


Minimum 

1 

I 
* 


Mjixiriimi 


All Files: 


Slot 

Drive 

Volume 


7 

2 

254 


Sequential 
Text Files: 


Byte 

Relative Field 

Absolute Field 


B 

R 
(EXEC) R 








32767 
32767 
32767 


Random-Access 
Text Files: 


Record Length 
Record Number 




L 

R 


1 

9 




32767 
32767 


Binary Files: 


Starting Address 
Number of Bytes 


A 
L 


9 

i 




65535 
32767 




DOS Comnand 




Quantity 


Range 
Minimum 


Maximum 




PR# s 
IN* s 
MAXFILES n 




m 
n 




1 




|6 ** 
16 ** 
16 


* Minimum volume number 1N1T 


will 


actually 


assln 


to a 


diskette 



. - 



** Maximum slot number built into the Apple II is 7. In deferred- 
execution mode only, the SYNTAX ERROR message is given for s values 
from 8 through 16. 

Note: The use of values outside the above ranges does not always cause the 
RANGE ERROR message- Any DOS command parameter or command quantity that 
Is less than 9 or greater than 65535 will cause the SYNTAX ERROR message, 
not the RANGE ERROR message. 



WRITE PROTECTED (ONERR GOTO code » 4) 

Occurs when DOS attempts to store Information on a diskette, but the disk 
drive does not detect a "write-protect" notch or cutout on the left side 
of the diskette's outer case. The following are the most likely causes: 

1. There is an adhesive label placed over the diskette's write-protect 
cutout, to prevent accidentally over-writing or deleting any information 
on the diskette. This label may be removed, whereupon 

BSAVE or WRITE to the diskette. 



DOS will SAVE or 



2. There Is no write-protect cutout on the diskette. This is true on the 
System Master diskette, for maximum protection. While not recommended, it 



Is pouibla to carefull y cut a notch of exactly the correct size and in 

tMCCly the correct place* Use another diskette's write-protect notch for 
a model . 

>. M you receive this message while RUNning the COPY program, and the 
G4MM Is not either I or 2, above, you may have inserted the diskette into 
the drive Incorrectly (in any other situation, DOS gives the 1/0 ERROR 

mcHsage to signal incorrect diskette Insertion). Check the diskette's 
position in the drive* and re-read Chapter l's discussion on inserting 
diskettes. 



END OF DATA (ONERR GOTO code - 5) 

Occurs when you try to retrieve Information 
where no information has ever been stored. 
In a sequential text file, or beyond the la 
random-access text file, may contain the va 
for a null character, a "nothing", and any 
retrieval of this character results in the 
that only OPEN automatically sets the posit 
the -file's beginning. The message usually 
command, and can arise in several different 



from a portion of a 
Any byte beyond the 



text file 
last field 
st field of each record In a 
lue 0. Zero is the ASCII code 
command that causes the 
END OF DATA message. Remember 
ion-in-the-f lie pointer back to 
occurs after an INPUT or a GET 
ways: 

1. Too many successive INPUTs or INPUT with too many variables. Each 
INPUT or INPUT variable causes one additional, adjacent field to be read 
into the Apple. 



2. Too many successive GETs. 
or character into the Apple* 



ich GET reads one additional, adjacent byte 



3. The B (for Byte) parameter was too large. In sequential files, this 
parameter must not specify a byte beyond the last RETURN character in the 
Ella. In random-access files, the B parameter should not specify a byte 
beyond the last RETURN character in the currently selected record. 
Remember, the first byte in a file or a record is byte g. 

4, The R (for Relative-field position) parameter in a POSITION command was 
too large* In sequential files, this parameter must not specify a field 
beyond the last existing field in the file. In random-access files. 



POSITION'S R 
field in the 



paraneter should not specify 
currently selected record. 



a field beyond the last existing 



same as the R 
the file, 
only. 



Remember, the R parameter used with POSITION is not the 

paraneter used with READ* It specifies a field position In 

relative to the current file position and forward in the file, 

R0 specifies no change In the current file position* Rl jumps the file 

position ahead to the first byte following the field that contains the 

current position. 

POSITION scans forward through the contents of the file, byte by byte, 
looking for the Rp-th RETURN character. If it encounters a 9 byte (the 
null character) before finding the required RETURN character, the END OF 
DATA message is given Immediately : it is not necessary actually to INPUT 
or GET the null character* 
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too 



5* The R (for absolute-field position) parameter In an EXEC command was 
Urge. This parameter may specify the first field beyond the last 
existing field in a file, hut attempting to specify the second field 
beyond the file's end will cause the END OF DATA message. Remember, R0 
specifies the first field In a file* 

6* The R (for Record) parameter in a READ command specified a random-acc 
file record in which nothing has yet been stored. Before you can READ 
from a particular record in a random-access file, you oust first WKlTfc 

some information into that record. 

Remember, READ'S R parameter is not the sane as the R parameter used by 
POSITION or EXEC. READ'a R parameter specifics an absolute record in a 
file; R0 Is the file's first record, and so on. 

DOS uses the OPEN command's L parameter for calculating where the Rr-th 
record begins, so the OPEN preceding READ must use the same 1- parameter 
value as the OPEN that preceded WRITE for that file. 



FILE NOT FOOKD (ONERR GOTO code - 6) 

Occurs when certain DOS commands specify a file name that is not in the 

CATALOG for the diskette in the selected or default disk drive. Only the 

inds SAVE, BSAVE t INIT and OPEN can create a file whose name did not 



previously exist. In addition to these, CLOSE may be used with any valid 
name. A file name specified by any other DOS command must already exist on 
the diskette- 



This message may arise in various ways: I. You may have misspelled the 
file's name, by a typing error or by omitting the comma that separates 
file name from a following parameter. Check the CATALOG for the exact 
spelling of the file's name- Warning: if you have accidentally typed 
control characters into the name of a file, CATALOG will not display I 
For help, see "File Names" in Appendix P. 



the 



display these 



characters* 

2. The file is on another diskette. 



Check the CATALOG. 



3. The file has been accidentally DELETEd. Check the CATALOG. 

4. When you use the INIT command on a diskette, you specify a file name 
which DOS thereafter attempts to RUN each time you boot the system with that 
diskette in disk drive I. Unless you write a BASIC program, and save it 
using the name given to INIT, the FILE NOT FOUND message will be given each 
time the system is booted with that diskette in drive 1* If you can t 
remember the name of this "greeting program", you must re-INIT the disk, 

or run MASTER CREATE to rename the greeting program without destroying the 
contents of the diskette. 

VOLUME MISMATCH (ONERR GOTO code ■ 7) 

Occurs when the Volume (V) parameter used in a DOS command is not the tat* 
as the volume number assigned to the diskette in the default or selected 
disk drive, when that diskette was INITialized. The volume number of a 



ma 

sj-g 



V 

ra 



■t 



.!««■ 



± 




I 
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dm 

sU 

m :q 



Unless a DOS 



diskette la shown at the head of each CATALOG display, 

command apeclflea a particular volume, the diskette's volume number Is 
ignored, and no message is given. If a DOS command specifies volume 0, the 

diskette's volume number is still ignored. If no volume number Is given 
with 1RIT, or If volume number is given, the diskette will be initialized 
with the default volume number 254> 



I/O ERROR (ONERR GOTO code - 8) 

Occurs after an unsuccessful attempt to store data on a diskette or to 
retrieve data from a diskette (DOS tries 96 times, then gives up). This 
message can occur in the following ways: 

1. The selected or default drive's door is open. Close the door to the 
disk drive. 

2« No diskette in the selected or default disk drive. Put a diskette Into 
the drive and close the drive door. 

3* Diskette in the selected or default disk drive has not been 
INITialized. INIT the diskette. 

4. Diskette is inserted incorrectly. Check the diskette, and re-read the 
section in Chapter 1 on Inserting diskettes. 

5. During execution of a VERIFY command, DOS found the specified file was 

not stored correctly on the diskette. If the file's information is still 
in memory, try storing it again (perhaps on a different diskette). 

6. The DOS command's D (Drive) parameter has specified a disk drive that 
does not exist in this system. The default drive is now the non-existent 
drive. Just specify the correct D parameter with the next DOS command to 
reset the default. 

7. The system is trying to access a li-sector diskette using 16-sector DOS- 
Use the MUFFIN program to update your diskette to 16-sectors. 

8. The DOS command's S (Slot) parameter has specified a slot that does not 
contain a disk controller card in this system. 



i 



You are In trouble, but can still save yourself; don't despair. The 
problem is that the default slot is now the empty slot your lsst DOS 
command specified. The next DOS command without a slot parameter will go 

to the empty slot and return the same message as before. To reset the slot 
correctly, 

a) Press RESET 

b) If you see a Monitor prompt (*), type 3D0G 

c) Type CATALOG Ss where s is the correct slot. 



M9 



DISK FULL (ONERR GOTO code ■ 9) 

Occurs when DOS attempts Co score information on n diskette, and finds that 
no more storage apace is available on that diskette. A raximum of 496 

sectors can been filled with user-stored information, as displayed In the 
CATALOG (if an Individual file exceeds 255 sectors, the CATALOG display of 
Us length starts over again at 000). If you receive the DISK FULL 
message, rest assured that all files are CLOSBrf, and that DOS saved for 
you all it could (leaving you with some portion of your file not on the 
diskette). If you receive this message while saving a file called STUFF, 
the first thing you should do Is to 
DELETE STUFF 
and then save your program on another diskette that has more room left* 



If you receive the DISK FULL message and then immediately try to SAVE, 
BSAVE or WRITE any file on the diskette before DELEIYing any files, then 
(are you ready7) the sector length of the one of the entries ahovn in the 

CATALOG will be set to 0. Don't despair: despite the odd appearance of 
that entry's CATALOG display, the file itself is in fine shape. To avoid 
such situations, if you get a DISK FULL message, DELETE some files before 
trying to save other files* 



FILE LOCKED (ONERR GOTO code - 10) 

Occurs when you try to 5AVE, BSAVE, WRITE or DELETE using a file name that 

hap been LOCKcd on the diskette that Is in the selected or default drive* 
Check the CATALOG display: the names of LOCKed files are preceded by an 
asterisk ( * ) in the CATALOG display* A file is LOCKed to prevent 
accidental over- writing* Use another diskette or UNLOCK the desired file* 



SYNTAX ERROR (ONBtR GOTO code - 11) 

Occurs when DOS encounters a syntax error in a DOS coamand* Check the 
manual for the exact syntax required for the command in question* The 
problem may be a non-valid file name (see Appendix F) , an incorrect 

parameter syirbol, a ntiaslng parameter, a missing or Incorrect separator 
(usually a comma). This message will also arise if a parameter value or 
command quantity Is a negative number or is greater than 65535* 

Rarely, every DOS comand causes the Applesoft or Integer BASIC Syntax 
Error message* This usually means that DOS has not been booted or has 
become "disconnected" from input and output* Try pressing the RESET key, 
then typing 3D0C to reconnect DOS; or, re-boot the disk* 



J- 



•hi 



ft 




™* 



± 




m^ 




mhi 



■^3 
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NO BUFFERS AVAILABLE (ONERR GOTO code - 12) 

occurs when a DOS command requires another file buffer for input or 
output, and all the available file buffers are already in use* On booting 
the system, DOS reserves enough space In the Apple's memory for three 
lnput*nnd-output file buffers* A subsequent MAXFILES command can increase 
or decreafie the number of available file buffers, and a CLOSE command can 
release file buffers currently in use for text files* 

Many DOS commands use one file buffer for input or output during their 
execution, and then relinquish that buffer when execution of the command 
has ceased* 

When a text file is OPENed, a file buffer Is assigned to that file for 
input, and output- This buffer remains In use, generally* until its file 
is CLOSEd either specifically by file name or by the nameless CLOSE that 
de-allocates all the text-file buffers. A text flic is not automatically 
CLOSEd by a program's coming to an end* To conserve buffer space, CLOSE 
files as soon as you are through using them* Remember that the next OPEN 
will re-aet the poaition-in-the-f lie pointer to the file's beginning. 



* 



The HAXFILES command can be used to increase buffer space before writing 
the program or loading the program into memory. Increasing MAXFILES movei 
HI MEM down, and this can erase stored Integer BASIC program lines or 
Applesoft strings. Changing HAXFILES in the middle of a program can be 
especially dangerous ■ 



FILE TYPE MISMATCH (ONERR GOTO code = 13) 

Occurs when a DOS command attempts to use a file name that is already 
assigned to a file whose file type is Inappropriate to the present 

command. If you are sure the command is correct, use a file name that is 
not now on the diskette, use s different diskette. RENAME the existing 

file or DELETE th« existing file* 

This message arises from several different incorrect combinations of DOS 
commands with existing file types. Here are the correct combinations: 



LOAD f, RUN f, SAVE f 



CHAIN t 

OPEN f, READ f, WRITE «. 
APPEND f, POSITION f, EXEC f 

BLOAD f, BRUN f, BSAVE t 



f muat be an Applesoft or Integer 
BASIC program file. 

f must be an Integer BASIC program file. 

f must be a text file* 

i must be a binary program or data file. 



The greeting program's file name, specified with INIT or UPDATE, 
must refer to an Applesoft or Integer BASIC program file* 
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PROGRAM TOO LARGE (ONEKR GOTO code - 14) 

Occurs when a DOS command attempts to place a diskette file Into Apple** 

memory, and finds the available memory insufficient to contain the entire 

flic. You (or a previous program) may have set HIMEM too low for the 

current task* or a large MAXF1LES may have set BIMEM too low. If you set 

the number of file buffers to three, using the command 

MAXFILES 3 

then HIMEM will be returned to the booted value given in Appendix D, Table 




$> 



If you are In Integer BASIC, and HIMEM la set low (to protect the 
high-resolution screen memory, for Instance), you may experience trouble 
on shifting to diskette Applesoft* Diskette Applesoft occupies about 

12. 5K of memory, but a shift to diskette Applesoft (with ¥? or LOAD or 
RUN) does not reset HIMEM to maximum. When DOS tries to load the 
Applesoft program from diskette, the message PROGRAM TOO LARGE will be 
given If HIMEM is below about 13100. The system will be left in Integer 
BASIC again, and you must set HIMEM higher from Integer BASIC. See 
Appendix D, Table 2 for your system's maximum HIMEM with DOS and three 
file buffers* 




<s> 



»mory, 



In deciding whether or not a program will fit into the available 
DOS looks only at the number of diskette ggejorg occupied by the 
program* In general, the program does not completely fill the last sector 
(256 bytes), but DOS ignores this fact. DOS compares only the high-order 
byte of LOMEM (Integer BASIC) or HIMEM (Applesoft) with the high-order 
byte of the projected end-of -program location* Thus a program which 
should fit into memory, but which would leave less than 256 bytes of free 
memory after loading, may cause the PROGRAM TOO LARGE message. Sometimes 
this can be corrected by moving HIMEM or LOMEM slightly, to change the 
high-order byte, before loading the program. 



NOT DIRECT COMMAND (ONERB GOTO code - 15) 

Occurs when you try to use one of the text file commands APPEND, OPEN, 
POSITION, READ or WRITE from immediate-execution mode. These DOS commands 
can be used only from within PRINT statements in program lines* 



9 =3 
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This appendix tells how information is stored on a diskette, and how DOS 
remembers where particular information has been stored* 

In the following discussion, s dollar sign ( S ) or the label "Hex" 
preceding a number indicates that the number !■ expressed in hexadecimal. 



OVERVIEW OF THE STORAGE PROCESS 

In the Disk 11 system, information is recorded on a diskette In 35 
concentric zones or bands, called tracks. These tracks are nunbered from 
track $00» the outermost, through track 522, the innermost- The disk 
drive's recording and reading head can be moved in and out, to stop and 
hover over each of these 35 different zones of the spinning diskette. 

Furthermore, the length of each track on the diskette is divided into 16 
segments, called sectors. These sectors are numbered from $0 through $F t 
and up to 256 (SIM) bytes of information can be stored in each sector. 
Once the disk drive's recording and reading head is positioned over a given 
track, that track's 16 sectors will pass under the head, one after the 

other, each time the diskette spins around- D05 always records Information 
on the diskette in 256-byte chunks* exactly filling one sector each time- 
To store information on the diskette, DOS first puts 256 bytes (one 
sector's worth) of the information in an area of Apple's memory called I 
file buffer. When this file buffer Is full, the information is stored in 
one sector on the diskette. Then DOS fills Apple's file buffer with the 
next 256 bytes of information and stores that information on the diskette. 

In general, DOS will begin storing a program or text file wherever it can 
find sn unused sector on the diskette. When that sector la filled with 
its 256 bytes of information, DOS finds another free sector, perhaps on 

another track, and continues to record information there. This process 
continues until the entire file has been stored. 

To remember which sectors of which tracks contain the information for a 
particular file, DOS makes up a list of each track and sector used, as it 

stores the file. Then DOS stores that list, called a track/sector list, in 
yet another free sector (or sectors) on the diskette* 

Finally, the file's name, file*-type, length in sectors, and the diskette 
location of the file's track/sector list are recorded In a special area of 
track $11 called the directory. At this tlsw, too, the diskette's track 
bit map is updated to correctly show which sectors of each track are 
currently in use. 

WRITING INTO A SEQUENTIAL TEXT FILE 

Entries in a text file consist of I to 32767 characters stored as their 
equivalent ASCII codes and ended by a RETURN character {either ASCII $0D or 
ASCII S8D). Each such entry is called a field. 



124 






v 



5* 



E 

E 



e 

E 



In a sequential tent file (no length parameter specified when the file was 
npRNed), fields are stored immediately following each other (sec Chapter 
6). DOS writes the first byte of each new field immediately following the 
RETURN character that ended the previous field (unless otherwise 
instructed by a Byte parameter)* Each time the File is OPENed, DOS 
forgets the current position within the file, and starts WRITEing again in 
byte • (again, unless otherwise instructed by a Byte parameter). 



In order to re-write a particular field or character within a sequential 
file. WRITE can be used with the B (for Byte) parameter to begin writing 
at the specified, absolute byte of the file (the first byte in the file 
is byte *. the next is byte 1, etc-)- The byte specified may be before or 
after the current position in the file- 



x 



It 1b very difficult to rcneober exactly which character appears in every 
byte of a text file, especially in a sequential text file. For this 
reason, use of the Byte parameter in sequential text files is not 

recommended. 



The POSITION command can be used with an B (for Relative-field) 
parameter to move a pointer ahead (only) through the I tie a specified 
number of fields relative to the current position 
program portion such as 



in the file. 



Rl 



12* PMH1 M. -OPEN NRMES- 

13B P*fMT VK "POSITION MflrtES. 

14* PRINT 09- "WRITE hWHES" 

Ua PRINT "APPLE COMPUTER" 

1?V PRINT l>». -O.OSE NflDES- 



wlll attempt to WRITE the characters APPLE COMPUTER 
beginning in the first byte of the fourteenth field 
Relative-field 0). 



into the NAMES file, 
(the first field is 



X 



POSITION can move you to the first byte of any given field Relative to the 
current position in o sequential text file- If you then re-WRlTE that 
field, however, £ou must make sure that you re-PRINT exactly the same 
number of characters that you PftlNTed in that field originally. If you 
PRINT fewer characters, you will have created two new fields: the field 
you just PBINTed* and the tail-end of the original field you were 
over-writing. If you PRINT more characters than the original field 
contained, you will have over-written Borne of the characters at the start 
of the ne*t field- 
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WRITING INTO A RANDOM-ACCESS TEXT FILE 



random-access text Ell*, a Length parameter is specified when the 
a OPENed. The Length parameter determines the number of bytes in 

that DOS treats as a 
like a separate 



» which is a field or a collection of fields 

Each record in a random-access text file is 
tial text file whose maximum total length ha 

parameter- As long as you stay within that 
and re-WRITE all you want, without affecting 

WRITE can be uiaed with the R {for Record) and B (for Byte) 
ters to begin writing Into any byte of a specified record. 



i been specified by the 
maximum Length, you can 
any other record in the 



For a 

file 1 

record 

unit. 

ftequen 

Length 

WRITE 

file. 

pa raise 

s 

Since anjr DOS command will terminate WRlTE-ing, you cannot use POSlTtOH 
to Jump ahead into different fields within the record specified by the 
WRITE command. 



DOS uses the Length parameter to calculate where to write the first byce 
of each new record { L bytes beyond the first byte of the previous 
record). DOS simply skips over any bytes between the previous record's 
last character and byte L. The bytes skipped over will continue to 
contain whatever values were stored there at some earlier time (see the 
next section for details). 



® 



If you attempt to WRITE more characters in a random-access record than 

you specified in the Length parameter, all the characters are stored 

correctly on the diskette. However, when you begin WRITEing to the next 

record, DOS calculates the new record's starting position as U the " 

previous record had been within the specified Length. The new record thus 

overwrites the last characters of the previous, over-sized record, 

including the end-marking RETURN character of the previous record's last 
field. The result is messy. 



HOW DOS WRITES INTO TEXT RUES: GB4ERAL PROCEDURE 

When you WRITE a field into a text file, DOS first checks on the diskette 
to see whether or not you have already stored information in the sector 
which should contain that field. If your file has never used that sector 
before, D05 places zeros In all 256 bytes of an Apple file buffer, and 
then lets you put your information into chat buffer for later storage in 
the correct diskette sector. The contents of the file buffer are stored 
on the diskette when your information haa completely filled 256 bytes of 
the buffer, or when the file is CLOSEd. 

Thus, when you WRITE to a particular sector the first time , unused 
bytes are given the value zero. An attempt to READ a byte containing I 
zero (the ASCII code for the null character) will result In the messace 
END OF DATA 
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Bui if DOS finds your file has already s 
which should contain the field that you 
bytes from that sector into the Apple's 
changed any of those file-buffer bytes t 
the WRITE, POSITION (sequential files on 
of this for you — DOS then stores the h 
the the* name diskette sector where they 
file buffer are stored back on the diske 
byte not in the sector that was read int 
file is CLOSEd- 



tored information in the sector 
are now WRITEing, it reads all 256 
file buffer. After you have 
o contain your new information — 
ly) and PRINT commands take care 
uffer's contents right back into 
originated. The contents of the 
tte when you attempt to change any 
o the file buffer, or when the 



Q 



Thus, if you WRITE more information for a file, and DOS stores that 
information in a diskette sector already being used by your file, this 
will not re-writ© any zeros io unused bytes. Any of those sector bytes 
which you did not re-write will continue to contain whatever information 
mlfthi have been stored there before your WRITE command. This is true of 
thfl unused bytes at the end of a sequential text file, and also true of 
the unused bytes in each fixed-length record of a random-access text file, 



CONTBOS OF FILE SECTORS 



How that you know the general process of recording a file on diskette, we 
can discuss each element in more detail. The actual information stored, 
sector by sector, is different for each type of file. 



FORMAT OF FILE SECTORS 
for different file types 



File 

type 


Sector 


Byte 
(Hex) 




BASIC 


1st sector 


t 




(both 

types) 




1 
2 through 


FF 




Subsequent 


All 






sectors 


bytes 




Text 


All 


All 






sectors 


bytes 





Contents of byte 



Program length, low byte 
8 , high byte 



Token ized program 
Tokenlted program 



ASCII representation of 
text! one byte/character 
($00 marks end of file) 
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File 
type 

Binary 



Sector 
1st sector 



Subsequent 
sectors 



Byte 



1 

2 
3 

A through FF 

All 
bytes 



Contents of byte 



Starting RAM address, low byte 
" > high byte 

Length of RAM image, low byte 
, high byte 



Binary data 
Binary data 



THE TRACK/SECTOR UST 

As a file is stored on the diskette, DOS makes a list of the diskette 
locations used by the file- This track/sector list is then stored on the 
diskette in the same way the file Itself was stored- The contents of a 
track/sector list are as follow?: 



First Sector of a 
TRACK/SECTOR LIST 



Contents of by to 
Not used 

Link: track number where continuation of the 

track/sector list may be found. 
Link: sector number where continuation of the 





I 
2 



3 through 4 

5-6 
7 through B 

C 

1) 



10 
11 



FE 
FF 



track/sector list may be found. 

(If both bytes of Link - 0, no link.) 

Not used 

Sector base number (counts groups of 122 sectors) 
Mot used 



Track number of first file sector 
Sector 

Track number of second file sector 
Sector " ' 

Track number of third file sector 
Sector " 



Track number of 122nd file sector 
Sector 



128 



b 3 

* h 

b 4 

b 4 

b a 

B 3 

B 3 

B 3 

B 3 

* =J 

B 3 

■? 3 

B =3 

B R 

B =3 

B =3 

e 3 

B ^J 

B -3 

B: q 



If iiny track/sector pair is 0/0 this indicates an unassigned sector 
(usually the end of the file, although text files may contain 0/0 
Indicators for many as-yet-unassigned sectors where future bytes or 
records may be written)* 

Subsequent sectors of the track/sector list (if the list extends beyond 
122 track/sector pairs) are Identical to the first sector described above, 
except that the track/sector pairs refer to subsequent groups of 122 file 
sectors. Also, Link bytes 1 and 2 will be different for each subsequent 
sector. Each Link pair gives DOS the diskette location of the next 
portion of the track/sector list- If both bytes of the Link are 0, this 
indicates the final portion of the track/sector list. 

With a text file, only the track/sector pairs for those sectors actually 

containing information appear as non-zero in the track/sector list* DOS 
calculates the correct position for the track/sector pair within the list, 
filling unassigned track/sector pairs with 2eroe. 

Thus, if the Length parameter for a random-access file is 128 (two records 

per sector) and you WRITE only to record number 2700, thirteen diskette 
sectors are used: one for the contents of record number 2700, and twelve 

for the sectors of the track/sector list. The contents of records number 
through 2683 may someday occupy 1342 sectors; but until those records are 
written, they do not use any diskette space. The track/sector list giving 
the locations of the sectors containing records number to 2683 occupy 
eleven sectors* 



THE DISKETTE DIRECTORY 



On every initialized diskette, track $11 is reserved for information 
concerning the contents of the diskette. This is where DOS stores the 
directory containing, for each file, the file's nan*?, its file type, 
nunfcer of sectors occupied by the file (MOD 256), and the diskette 
location of the file's track/sector list. The CATALOG command cause 
most of this information to be displayed on the screen. Each sector 
diskette directory is formatted as follows: 



the 



of a 



Byte (Hex) 
I 

1 
2 



One sector of a DISKETTE DIRECTORY 
Contents of byte 



Hot used 

Link: Track number where continuation of the 

directory may be found (normally $11) 

Link: Sector number where continuation of the 

directory may be found 
(If both bytes of Link - 0, no link.) 
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Byte (Hex) 

3 through A 

B through 2D 

2E through 50 

SI through 73 

7 A through 96 
97 through B9 
BA through DC 

DO through FF 



Contents of byte 



Not used 

Directory entry for file I 

Directory entry for file 2 

Directory entry for file 3 

Directory entry for file 4 

Directory entry for file 5 

Directory entry for file 6 

Directory entry for file 7 



(see below) 



The file numbers shown for the seven directory entries sre arbitrary- When 
a file is DELETEd, DOS marks the directory entry for that file (see 
following table). The next time a file Is stored, DOS replaces the old 
narked directory entry with the directory entry for the new file* Thus, 
while DOS originally fills the directory in the order shown, file 
DQ,ETEions soon render this order meaningless. 

The diskette directory begins in crack $11, sector $F. if more space Is 
needed to store additional directory entries, sector $F is Linked to sector 
$E. If still more space is needed, sector $E Is Linked to sector $D, and 
so on, through sector SI* This allows the directory to store directory 
entries for a maximum of 105 different files. 

Each directory entry is written In the following format: 



Relative 
Byte (Hex) 



DIRECTORY BHTPT FOR ONE FILE 
Contents of Byte 



1 

2 

3 through 20 

21-22 



Track number of the file's track/sector list 

(The original value Is copied into 20 and the value 
of byte is changed to $FF when the file Is 

DELETEd.) 

Sector number of the file's track/sector list 

File type (see discussion on the next page) 

File name 

Sector count: the number of diskette sectors 
{MOD 256) occupied by the file 
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ft 



m 

Ei 
E 



j 



i 

e4 



3 



i 



A directory entry's relative byte specifies each byte within the entry, 
although each entry starts at a different actual byte number within the 
directory sector. To find the absolute sector byte corresponding to a 
relative byte, add the relative byte to the entry's first absolute sector 
byte (as listed in the previous table). 

Because only one byte is used to store a file's sector count, the maximum 
directory sector count Is 255 (SFF). If a file exceeds 255 sectors, its 
sector count (as displayed by CATALOG) starts over again at 000. This 
does not affect use of the file, but may give an erroneous impression of 
how full the diskette is. 

The eight bits of a file's type-designating byte, relative byte number 2 
in a file's directory entry (see previous table), are assigned values as 
foil ows : 

BYTE INDICATING THE FILE TYPE 



Bit 

7 



6 
5 

4 
3 



CATALOG 
symbol 



File type designated 



File is locked (write protected) if this bit 
File is unlocked (not protected) if this bit 

Expansion type for future use (normally zero) 



1 




ii 
■■ 
■t 



ii 
it 



M 
II 



2 
t 




A 
I 

T 



Binary file if this bit - 1 

Applesoft BASIC file if this bit - 1 

Integer BASIC file if this bit - 1 

Text file if bits through 6 are all rero 



The file type is determined by a 1-bit appearing In one of the bits 
through 6. If bits through 6 are all 0-bits, the file type defaults to 
a Text file* 

The file's type-designating byte can thus take on the following values: 

VALUES FOR BYTE INDICATING FILE TYPE 



File 




Value 


: of T 


ype t 


>yte (Hi 


an) 


tvpe 


File 


unlocked 




Fll 


e locked 


Text 













69 


Integer 




1 








81 


Applesoft 




2 








82 


Binary 




4 








84 
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VOLUME TABLE OF CONTENTS 

Sector $0 of track SI 1 contains the diskette's Volume Table of Contents, or 
VTOC* The VTOC stores the following information: 



Byte 
< Hex) 



1 
2 



Not used 

Track number of first directory sector 
Sector 



4 
5 



7 through 26 
27 

28 through 2F 



VOLUME TABLE OF C0NTEHTS (VTOC) 
Track $11, Sector $0 
Value 
( Hex) Description 

2 

11 

0F 

4 



I through FE 



7A 



DOS release number 

Not used 
ii ii 

Diskette volume number (default: $FE) 

Not used 

Maximum number of track/sector pairs possible 
in each sector of a track/sector list 



30 FF 

31 FF 

32 00 

33 00 

34 23 

35 0F 

36 00 

37 01 



Not used 



These four bytes are a mask for the 

track bit maps (see next 2 pages): 
each 1-bit enables one of the 16 

sectors to be used In every track. 
Number of tracks per diskette 
Number of sectors per track 



Kunfcer of bytes per sector, low byte 
" ' high byte 



38 through 3B 
3C through 3F 

40 through 43 



44 and 45 ? 

46 and 47 

( Continued on next page J 



Track bit map 
Track I bit map 

Track 2 bit sap 



Track 3 bit map 



(These tracks 
not available 

to the user) 



■ta 

E 

E 

E 

E 
E 



E 
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Byte 
(Hex) 


Value 
(Hex) 


48 and 49 
4A and 4B 

• 


• 


* 

78 and 79 
7A and 7B 


• 
■> 

i 


7C through 7F 





80 and 81 
82 and 83 





* 


• 


* 
* 

C0 and CI 
C2 and C3 


* 
* 

? 

# 


C4 through FF 






Description 



Track 4 bit map 

It II II I* 



Track $10 bit map 
ii n n tf 



Track $11 bit map (Directory 6 VTOC) 



Track $12 bit map 
ii ii it ii 



Track $22 bit map 

II II It II 



Hot used 



TRACK BIT MAP 

Starting in byte $38 of the VTOC (see previous table), subsequent four-byte 
groups each contain the track bit map for one of the diskette's 35 tracks. 
The arrangement of 1-bits and 0-bits within a track's bit map shows DOS 
which sectors of that diskette track are currently in use, and which 

sectors are free. The bit map for each track uses the following format: 











TRACK 


BIT MAP 












For 


one 


diskette 


track 








D 


esignated 
Sector 












De: 


aignated 
Sector 


fte 


Bit 


(Hex) 










Byte 


Bit 


(Hex) 


1st 


7 

6 
5 

* 
3 
2 

1 
* 


T 
E 
D 

c 

B 

A 
9 
8 










2nd 




7 

6 
5 

4 
3 
2 
1 
















3rd 


& 6th 


All 


Spare 
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IE * bit In thr track bit 
corresponding Co that bit ia 
0, the sector corresponding 



contains the value I, the 
free* If a bit In the map 
to that bit is currently in 



sector 

contains the value 
use- Bits marked 



The track bit 



'Spare' in the table above contain the value 0; these bits are not used. 

for a typical track might appear as follows: 



TYPICAL TRACK BIT HAP 

2nd byte 3rd byte 4th byte 



1st byte 
11 



1 1 I 1 1 ] 1 1 



M 1 1 1 III 1 1 1 1 1 1 t t 



F E D C B A 9 



7 6 5 4 3 2 10 



00000000 
i Spare 



00000000 



Sectors designated 



Not und 



1 • Free sector 
- Sector In use 



(assuming the corresponding bit of the Enaak , 
VTOC bytes $30 through S33 t is also I) 



When a file is being stored on the diskette (using WRITE, 
an entire track is allocated to the file ac once (when po 



SAVE or BSAVE), 
sible), and the 
track's bit nop shows the entire track in use. Then* when the file is 
CLOSEd, those sectors not actually used are again designated as free* in 
the bit nap for that track. 



a> 



Sectors actually used to store a file's information, however* can only be 
"set free" when that file name is DELETEd. Suppose your diskette contains 
a 100-sector BASIC file naned BIG, for instance. If you now SAVE, on the 

sane diskette, a 2-aector file with the same nane Bin (overwriting the old 

file) a CATALOG of the diskette will reveal that your 2-sector file BIG Is 

still using up 100 sectors* To free up unnecessary sectors used by a 

BASIC file named BIG, use the following sequence of comnands: 

LOAD BIG 

DttETE BIG 

SAVE SIR 

A similar process 

binary files. 



can be used to release unnecessary sectors used by 



To release unnecessary sectors being used by a text file, you will have to 

READ each of the file's fields into the Apple. If you store all the 
fields in an array, you can then DELETE the original file before URITElng 
each record hack onto the diskette using the original file name. Another 
way to do this is to read each field into the Apple and immediately WRITE 
the field back onto the diskette using a file name that is different fro* 
the original file nane. When you have read and re-written the last field, 
you can DELETE the original file. 
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TRACK AND SECTOR ALLOCATION ORDER 

Each diskette contains 35 tracks, three of which are reserved for DOS and 
one for the Directory, leaving 31 tracks for the user- Each track 
contains 16 sectors* so all together 31*16 or 696 sectors are available to 
the user* 

5ectors are filled starting with sector $F and working back to sector SB- 
Tracks are first filled starting with track $12 (just inside the 

directory /VTOC trade) and proceeding inward to track $22 (the innermost 
track). When track $22 has been filled, tracks are then filled starting 
with track $10 (just outside the directory/VTOC track) and working outward 
to track $3 (the outermost track available to the user)* 




Directory/VTOC) 



^Diskette 
Cover 



TRACK ALLOCATION ORDER 



SECTOR ALLOCATION ORDER 



First 

Filled 

First: $12 

Then: $10 



Last 

Filled 

-> $22 
-> 903 



First 

Filled 



Last 
Filled 



SF > $0 
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RETRIEVING INFORMATION FROM THE DISK 

To retrieve a file fro* diskette* DOS follows the process used to store 

the file* but in reverse* After a command such as 

LOAD FILE 

or 

BLOAD PILE 

for instance, DOS floe* to the diskette's file directory in track S1I, and 

finds the directory entry containing the name PILE, This entry also 

contains the diskette location (by track and sector) of the desired file's 

track/sector list* DOS then goes to this track/sector list, and reads the 

first track/sector pair* This pair specifies the diskette location of the 

first sector containing the program named PILE. When DOS has read that 

first sector of program into the Apple, it returns to the track/sector 

list for the location of the program's second sector, and so on* 



MAD ING FROM A SECHJBfTIAI. FILE 

When READing from a sequential text file, with a program portion such as 

50 PRINT DS; "READ TEXTFILE" 

60 INPUT AB 

for instance, the general process Is like that described for LOADing a 

program file. However, only the sector containing the text file's next 

field (.in characters fron fch* currmt position in th« Flit through I hi 

next RETURN character) is road into the Apple's file buffer in response to 
the INPUT command* Then the actual sector bytes that make up the desired 
field are assigned to the variable AS. This process is repeated if the 
field extends over more than one diskette sector. Each subsequent INPUT 
command will cause reading of the file to resume, from the Apple's file 
buffer if tt already contains the proper field, or by reading another 
diskette sector into the Apple* This continues until the last field is 
read or some command CLOSE* the file* 



By using the READ command with the B (for Byte) parameter, you can cause 
the next INPUT to begin reading from the specified absolute byte in the 
file (the file's first byte Is 0, the next Is 1, etc). This byte may be 
before or after the current position within the file- To use this 
parameter effectively, however, you must know the contents of every byte 
in your file* The POSITION command uses the R (for Relative-f icld) 
parameter to move DOS's current—position pointer the specified number of 
fields forward (only) through the file, relative to the current position 
in the file. Each time you OPEN a file, DOS forgets its current position 
in the file ond starts READing again from the beginning of the file 
(unless otherwise instructed by a Byte parameter)* 



s 



The INPUT comeiand treata a response somewhat differently in Integer BASIC 
and in Applesoft* If certain characters such as the colon or comma appear 
in the response field, further characters in the field may be Ignored or 
assigned to multiple INPUT variables (if any). For details, see the 
appropriate manual for Integer BASIC or for Applesoft* 
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RCADING FROM A RANDOM-ACCESS FILE 

The text-reading process la somewhat different when READing from a 
specified record of a random-decess text file (also see WRITING TO A 
RANDOM-ACCESS FILE in this appendix). In a randoft-access text file, each 
record is composed of the same number of bytes, specified in the Length 
parameter when the file was OPENed prior to WRITElng the file. When this 
same file is OPENed prior to READing it, an identical Length parameter Is 
given. To find the beginning of a particular record (specified by the 
READ command's R parameter), DOS uses the Length parameter to calculate 
the number of bytrs occupied by all the preceding records. That number is 
then divided by 256 ($100) to determine how many file sectors DOS must 
skip over to reach the sector containing the desired record. Then DOS 
examines the file's track/sector list and finds the diskette location of 
the desired file sector. Finally, DOS reads the correct sector into the 
Apple's file buffer. Then the correct bytes can be read from the file 

buffer. 



^ 



This some retrieval process would be followed even if the text file had 
originally been stared as a sequent ial file, »r as .1 random-access file 
using a completely different Length* DOS blindly calculates the sector 
and byte position of the requested record according to whatever Length 
parameter you specify when you OPEN the file prior to READing from it, 
regardless of the Length parameter (if any) that was used when WRITEing 
the file in the first place. 



By using the READ coamand with both R (for Record) and B (for Byte) 
parameters, you can cause the next INPUT to begin reading from the 
specified absolute byte in the specified record (each record's first 
byte is 0, the next is 1, etc.). This byte may be before or after the 
current position within the record. To use this parameter effectively, 
however, you must know the contents of every byte in the specified record. 

The POSITION command, while primarily intended for access to sequential 
files, can be used with the R (for Relative-field) parameter to move 
DOS's current-position pointer the specified number of fields forward 
(only) through the current record, relative to the current position in the 
record. READ is used with the R (for Record, this time) parameter to 
move the current-position pointer to the beginning of the desired record. 
Using POSITION cancels READ mode (without resetting the position-pointer), 
and another READ (this time, with no^ parameter) re-instates READ mode. 



Each time you OPEN a file, DOS forgets Its current position in 
and starts READing again from the beginning of the file (unl 
instructed by a Byte and/or Record parameter). 



the file 
otherwise 



® 



format ■ 



DOS keeps no information for you concerning the structure 
record- length, or field-length of your text files. To use your 
random-access text files effectively, vou must keep detailed written 
information about the structure of these files, or keep the information 
the beginning of the file*. 



at 



137 



140 Humor y ktm/u 

Ul ttaaory Atms Ditd by DOS uid Rithar BASIC 

U2 HtMEH Set by Booting DOS 












TABLE 1: APPLE II MEMORY MAPS 

A. MEMORY AREAS OVER-WRITTEN WHEN BOOTING DOS 



Location on 
any system: 

Highest RAM 
■emory address 



DOS moves 
HIHEH here- 
[ Note 2 ] 

16383 <S3FFF>- 



7424 (S1DB0J- 
6912 (S1B00)~ 
2 303 (S8FF)- 
2048 ($800) 
1023 <$3FF>- 



512 ($20#> 



8960 

($2 300) 

bytes 



Relocated DOS, 
on completion 
of boot 



7 bytee not used 



1792 

($700) 
bytes 



r 



Three file 
buffers of 
595 ($253) bytes 
for input & output 



DOS, where first booted 

from a Master diskette 
[ Note 1 ] 



DOS Relocation Code 
[ Note 1 J 



Pirst stage boot 
starts here 



"Nibble" buffers 
used during boot 



Location on a 
48K system: 

.49151 (5BFTF> 



.0192 (S9D00) 
♦0184 (S9CF8) 



38400 (S9600) 



Lowest RAM 
Memory address » 

000 (50P0) 

Note 1* This memory area is not affected when booting a Slave diskette: 
DOS is placed directly below the Highest RAH Memory address that was 
available on the system that initialized the Slave diskette, whether 
appropriate to the present system or not. 
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B. MEMORY AREAS USED BY DOS AND EITHER BASIC 



Highest RAM 
memory address: 



Without DOS. 
either BASIC 



49151 (SBPFF) 
>n a 48K system 


10752 Disk 
(S2A00) Operating 
bytes System 

(If booted) 


sets HIMEM here 
t Note 2 ] 

Booting DOS 
.-—sets HIKE* here 


24576 


lnteget BASIC Applesoft 
program lines strings 
start at HIMEM start at HIMEH 
and build down and build down 


[ Note 2 ) 


(56000) "* 
16384 _^ 


High-resolution graphics m Page 2 
( Note 5 ] 




(S4000) 
8192 


High-resolution graphics. Page ! 

" " 1 
I Note 4 1 l 

, i 


FP (diskette) 

"sets LOHKM at 

12291 ($3003) 
| Note 2 1 


($2000) ~ * 


1 

Diskette 




2048 . 


~| Appleaoft 

Either BASIC'S 1 (If used) 
variables occupies 

start at LOHEM this space 
and build up 1 Note 4 1 

Applesoft 
program lines i 
push LOMEM up l 


FP (firmware) 
. and 1HT sat 


— *- — **-> ' 

($0800) 
Lowest RAM 


BASIC System use: 
low-resolution graphics 
and text screen, etc* 


LOHEM here 
[ Note 2 ) 


nemory address* *" 
0000 ($0000) 


31)0 " 3FF DOS + System 


Vectors 
Reserved 




300 - JCF 




300 * 


Monitor and BASIC Workspace 





Note 2- If your system is in Integer BASIC* the HIMEM pointer can be found 
(low byte first, then high byte) in locations 76-77 ($4C-$4D) . If your 
system Is In APPLESOFT BASIC, the HIMEM pointer is In locations 
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115*116 ($73-$74), 5aae format. See Table 2 for the value of HIHEH set by 
booting DOS. Increasing MAXFILES will move HIHEH down an additional 595 
bytes for each file buffer added. For the locations of other Applesoft 
program pointers, consult your Applesoft II BASIC Programming Manual, 
Appendix I. 



TABLE 2: HIMEM VALUE SET BY BOOTNG DOS 

When DOS is booted, HIMEM is set according to the amount of memory in the 
system: 



System 


Highest 


RAH address 


size 


Decinal 


Hexadecimal 


16K 


16383 


S3FFF 


20K 


20479 


S4FFF 


2AK 


24575 


S5FFF 


32K 


32767 


S7PFT 


36K 


36863 


S8FFF 


48K 


49I5I 


$BFFF 



HIHEH: set by DOS boot 


Decimal 


Hexadecimal 


5632 


SI 600 


9728 


$2600 


13824 


S3600 


22016 


55600 


26112 


$6600 


-27136 


S9600 [ N 



- 3 1 

Note 3, The number -27136 could also be written 38400, but Integer BASIC 
will not accept numbers greater than 32767. In Integer BASIC, memory 
addresses greater than 32767 Must be expressed as their negative 
equivalents- The negative equivalent of any positive decimal addrees n is 
( n - 65536 )• 

Note 4. Using high-resolution graphics Psgl i KMU the contents of 
memory locations 8192 through 16353, Unless DOS sets HIMEM to a value 
greater than 16383, an attempt to use high-resolution graphics Page I will 
erase part of DOS, This means that you cannot use Disk II and 
high-resolution graphics at the same tine, unless your system contains at 
least 32K of memory. 

If you are using diskette Applesoft, an attempt to use high-resolution 
graphics Page I wilt erase part of Applesoft- With diskette Applesoft* 
you may use high-resolution graphics Page 2, only, if your system contains 
at least 36K of memory- See Note 5. 

Note 5- Using high-resolution graphics Page 2 erases the contents of 
memory locations 16364 through 24575- Unless DOS sets BIMEM to a value 
greater than 24575, an attempt to use high-resolution graphics Page 2 may 
erase part of DOS- This means that you cannot use Disk II and Page 2 
high-resolution graphics at the same time, unless your system contains at 
least 36K of memory. 
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DOS BURY POINTS 



Routine to re-connect DOS (if page 3 Is over-written): 



System 

48K 
32K 
16K 



Decimal address 

< CALL > 
-25153 
23999 
7615 



Hexadecimal address 

S9DBF 
S5DBP 
$1DBP 



The Monitor command 3D0L disployn this number at the top right. 



Locations containing the start address and length of a BLOADed program: 



System 

48K 
32K 

16K 



Start address (low byte) 
Decimal .. Hexadecimal 



Program length (low byte> 

Decimal Hos adfcim.il 



43636 
27250 

1086b 



$AA?2 
S6A72 

S2A72 



43616 
27232 

108'. 8 



SAA60 
S6A60 
S2A60 



To see the starting address or length after a BLOAD, type 
PRINT PEEK (low byte) + PEEMlow byte +1)»256 

Program to find the DOS locations containing the starting address 
and length of the most recently BLOADed program, on any size system: 
5 PER BLORD FINDER 

7 H - 3©*0B REM PQS-6tGGT HIKE* 

8 T - 49X32 ROI HIGHEST ADDRESS 
10 0» » CHR» <*'-•: REM CTRL-D 

2© PRINT Dfe "BSflVE FOO. M777T, L#?7" 

30 PRINT [>*, "BLOflD FOO- 

48 PRINT V*> -DELfTE FOO" 

56 FOR I « M * 1792 TO T 

60 IF PEEK <l> < > 119 OR PECK 

<] + 1> < > 119 THEN NEXT I 
78 PRINT "LOCATIONS OF START 

ADDRESS -. li", ".'I * 1 

B6i FOR I • H + 1?92 TO T 

9© IF REEK <I* t > 119 OR PEER 
CI * 1> C > B THEN NEXT I 

106 RRINT -LOCATIONS OF LENGTH: " 

i 1. *j "■: I * 1 

The values of H and T (lines 7 and fl) arc shown for a 48K system. 
Appendix D, page 142, shows the correct values for your system. 
This program takes about 2 minutes to find the desired locations. 



DOS character input and output routines: 

See Chapter 10, cxpeclolly Bote 7 on page 105. For an example 
using the technique described, see the program on page 151. 
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CIRCUIT SCHEMATIC: DISK II INTERFACE 
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CIRCUIT SCHEMATIC: DISK II ANALOG BOARD 



APPENDIX f 
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Y OF DOS COMMANDS 
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The D05 commands are grouped Into 5 categories in this appendix: 



Housekeeping commands 

IN IT RENAME 

CATALOG DELETE 

SAVE LOCK 

LOAD UKLOCK 
HUM 

Access Commands 

FP PR# 

IHT 1N# 



VERIFY 
HON 
NOMON 
KAXFILES 



CHAIN 



Sequential Text File Commands 
OPEN APPEND 

CLOSE POSITION 

READ EXEC 

WRITE 

Random-Access Text File Commands 



OPEN 
CLOSE 



READ 
WRITE 

V i ]i- Commands 



Machine Lan^ua^e 
BSAVE 

BLOAD 
ISRUN 



Procedures used in DOS (Including chaining in Applesoft) are summarized in 
Appendix d The notation used In the summaries (and throughout the 
manual) is described In the following section* 



NOTATION 

Syntax refers to the structure of a computer command. 
is used to describe the syntax of each DOS command. 



A simple notation 



Iters in square brackets, [ and 1 , are optional. These items are 
sometimes called parameters. Hot all commands permit all parameters, but 
those parameters that are permitted in a given command may appear in any 
order, unless otherwise noted* 

If a command uses a file name, the file name must come Immediately after 
the command word itself: the first item following the command will be 
treated as a file name. The file name must be separated by a comma from 
any parameter that follows. 

Curly brackets may be used to indicate when a certain key should be 
pressed: 

(CTRL) hold down the key marked "CTRL" while another key is typed. 

<CTRL}D means hold down the CTRL key while you type the 
letter D. Sometimes another notation is used: CTRL-D means 
the same as (CTRL)D. 






. 
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(RETURN) press the key marked "RETURN". The (RETURN) required 

after every command is not shown* 

(RESET) press the key marked "RESET". 

<RSC) press the key marked "ESC". 



CAPITAL letters and commas must be typed as shown. Lower case letters 
stand for items that you must supply. 

f file name. This is from one to 30 characters. Any typoable 

character except the comma may appear in a file name. The 
First character must be a letter of the alphabet. For more 
details, see the next section. 
Examples: CHESS 

RECIPE 

SUH OF SQUARES 

NEH45 

ROU-ABOUT-THIS 

g another file name. 

Example: SEPARATOR WITH LOW VELOCITY 

s slot number. s specifies the Apple II slot in which the 

disk controller card has been placed (usually slot 6) . 
s initially defaults to the slot from which DOS was booted. 
It subsequently defaults to the last value specified for this 
parameter. & must be in the range 1 through 7. 
Examples: 7 
2 



{^5 



If s refers to a slot which does not contain a disk controller 
card, the system may stop and a program in memory may even 
be lost. See I/O ERROR, In Appendix B, for more details. 



v initially defaults to the 
from which the system was booted, 
specified for 
CATALOG command. 



volume number of a diskette. 

volume number of the diskette 

It subsequently defaults to the latest value 

this parameter, or implicitly specified by a 

v must be in the range through 254. 

Example: 101 

Note: A diskette's volume number may not be 0. In a DOS 

command, specifying a volume number of or simply V 
with no number is a "wild card" and tells the DOS to 
determine and use the volume number on the diskette- 
drive number (cither 1 or 2). d initially defaults to one< 
It subsequently defaults to the latest value specified for 

this parameter* 

Example: 2 
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position number. Used with the R parameter in the POSITION 
and EXEC commands for sequential text files. p specifies 
a field whose position In the file la p fields ahead of the 
current file position. p defaults to 0, which does not move 
the file-position pointer in the file- Note: EXEC always acts 
the pointer to the start of the nawed file, so p is always 
relative to when used with EXEC- See command summaries later 
in this Appendix. p oust be in the range through 32767. 

record number. Used with the R parameter in the READ and 
WRITE commands for random-access text files. r defaults 
to sfter OPEN. Thereafter, it defaults to the last record 
specified. r points to an absolute record within a randoo- 
access file. r must be in the range through 32767. 

address in RAH. The a parameter is required with the BSAVE 
command- a specifies the starting Apple memory address for 
BSAVElng or BLOADing binary information. If BLOAD does not 
specify an a parameter* then the value of a defaults to 
that used when the binary file was BSAVEd, a must be in 
the range through 65535. 

byte number- b defaults to 0- In a sequential file, b 
points to an absolute byte within the file- In a random-access 
file, b points to an absolute byte within the record pointed 
to by r - b must be In the range to 32767- For most 

applications b is in the range through the last byte in 
the current sequential file or the last byte in the current 
randomise cess record . 

length specifier- j defaults to U When used in the OPEN 
command with random-access files, J is required and specifies 
the number of bytes that will constitute a record in a random- 
access file. When used with the BSAVE command, ] is required 
and specifies the number of bytes of Apple memory* starting at 
address a , whose contents are to be stored on diskette. j 
must be in the range through 32767. 



As an example of this notation* the DOS command that la notated 

INIT f l,Vv] [ f Ss| [,DdJ 

can be interpreted as 

INIT HELLO, VI7, D2 

by the following process. The keyword "HIT" is in upper case, and must 

be typed exactly as shown- In the syntax description, "f" is lower case 

and stands for a file name — it is replaced by the legitimate file name 

"HELLO" In this example. The ",V17" is optional. "V" stands for 

"volume"; 17 was chosen arbitrarily as a volume number for this example. 

The notation ",Ss" is optional and omitted. The notation ",Dd" becoraes , 

D2 in this example, indicating that disk drive number 2 Is to be used. 

Any numerical constant in a DOS commend can be entered In hexadecimal 
notation by precceding the hexadecimal digits with a dollar sign. 



m 3 



*" =* 



e =1 



FILE NAMES 



Flit iwmw'n may be up to 30 characters long, and must begin with a letter. 
Thr name cannot contain a comma, a CTRL-M or a RETURN, which is used to 
terminate the command. Spaces that precede the first non-space character 
In a name are Ignored. All name characters beyond the 30th are ignored. 



x 



When typing file names, the use of special keys such as ESC, the 
left-arrow and right-arrow keys, and certain keys typed with the CTRL key 
("control" characters CTRL-C, CTRL-H) may have unexpected effects. 



$ 



If a file name contains control characters, you won't see them printed, 
hut they must be typed to use or delete the file- 



Ttte following Applesoft program can be used to find any hidden characters 
except Cm-W (RETURN), ESC, CTRL-H (left arrow) and CTRL-U (right arrow), 






Tfl 5i5fe 



7 I 









If you suspect you may have accidentally introduced a control character 
Into a file name, type this program, SAVE it, and RUN It. The Applesoft 
prompt ( 1 ) will be displayed- Neit type 
<:ataloc 

and you'll get a list of all the files, with any control characters shown 
as flashing characters- Control characters in program listings can also 
be iound this way. To re-instate normal printouts, type 

H" 



HOUSEKEEPING COMMANDS 



INIT f I P Vv) |, 5s) I,Dd] 

Kxomple: INIT HELLO, V18 

The paraneter v assigns a volume number to the diskette being initialized, 
Dctatlft on Initializing diskettes are in Chapter 2 and Appendix G. 
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CATALOG [»Ss] l»Dd) 

Example: CATALOG 

Displays on the screen the volume number and a list of all files on the 
diskette in the specified or default drive- The default volume nuiiber is 

changed to match that of the indicated diskette* If this command uses a 
volume parameter I,Vv) that parameter is ignored- 

With each file is displayed an indicator of its file type and the number of 
diskette sectors occupied by the file- The file types are: 

I Integer BASIC program file, created by SAVE* 

A Applesoft BASIC program ftle t created by SAVE* 

T Text file, created by OPEN and filled by WRITE. 

B Binary memory-image file, created by BSAVE* 

An asterisk beside a file's type indicator shows that the file is LOCKed. 

A maximum of 496 diskette sectors are available to the user* Each diskette 
sector can store up to 256 bytes of Information* Tha minimum length of a 

file is 1 sector, for an empty text file* (Technically, that 1 sector ts 

ipty track/aector list for the file*) Empty Integer 

and Machine Language files take 2 sectors* (I for the 

and 1 for the first program sector, which contains the 

See Appendix C for more details*) 
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occupied by the ei 
BASIC, Applesoft, 
track/sector list 
program's length. 



$ 



If an Individual file exceeds 255 sectors, the CATALOG display of that 
file's length starts over at 000. This does not affect use of the file, 
but may give an erroneous impression of how full the diskette Is* 



SAVE f.USa] f.Dd] [,WJ 
Example: SAVE COLOR DEH05. V56 

If there is no file with the specified file name on the diskette in the 

specified or default drive, a flit is created on that diskette and the 
current Integer BASIC or Applesoft program is stored under the given file 
name* If the diskette contains a file with the specified file name, but 
of a different language or file type, then the message 

FILE TCPE H1SMATCH 
will be displayed* 



da 

dd 

= 3 
■ 4 



3 
=1 



^ 



If the chosen diskette already contains a file with the specified file 
name, and in the same language, the original file's contents are lost and 
the current BASIC program is saved In its place. Ho warning is given* 
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LOAD f [,Sn| I JM! [.VvJ 

KfcMplei UW) HOW JONES, VI9, M 

Attempt* to find Integer BASIC or Applesoft program file with name f on the 
diskette In the specified or default drive- If the volume numbers match and 
than lit such a file, that program will he LOAflcd into the conputer. It can 
them be LISTed, or RUN* or SAVEd as with any program. LOAD closes any open 
text f lies, changes the Apple to the correct language for file f . and 
ernern any program In memory before placing the new program in the Apple. 

it file I i- hi Applesoft BASIC program, and Applesoft is not already In 
memory or available from the Applesoft firmware ROM card, the program 
AppJecnft will be LOADcd and RUN from the specified drive automatically* 
before file f Is LOADed* If Applesoft Is not on that diskette nor on the 
Tinware ROM card, the message 
LANGUAGE NOT AVAILABLE 
will he displayed* 

The Instruction LOAD, without any parameters, will LOAD a program from 
cassette tape- 



RUN f USs] l.Dd] [ t Vv] 
Example: RUN ANNUITY, D2 

LOADs file f from the specified or default drive <sce the previous 

discussion), then also RUNs the program loaded. If Just 

RUN 

ta typed, the program In memory is RUN* 



RENAME f, g l.Ss] UN] [,W] 

Kiample: RENAME SEPERATE, SEPARATE, 54, Dl , V0 

Kinds the file named f on the diskedte In the specified or default drive, 
mnti changes its name to ft . The file's contents are not affected* If file 
f was open, it is closed* 
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RENAME does not check to see whether the file name g is already In use, 
so It Is possible to use RENAME to put several files of the same name onto 
a diskette — a potentially confusing situation, at beat. 
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DELETE f (,Ss] [,Dd] [,Vv] 

Example: DELETE TEST 

Removes the file named f from the diskette In the specified or default 
drive* If f was open, this command closes it* See Appendix C for more 
details of the deletion process. 



^ 



If a file named f does not exist on the diskette* the message 
FILE NOT POUND 

will result. To avoid this occurrence stopping your programs, firat OPEN 
the file t then DELETE it- 



LOCK f [,Ss) I.Ddl [,Vv] 

Example: LOCK LOVE LETTERS, V31 

This command allows you to make file f , on the diskette In the specified 
or default drive, safe from accidental deletion or change. A LOCRed file 
is Indicated In the CATALOG by an asterisk ( * )• 



UNLOCK f USs] [,Dd] [.W] 

Example: UNLOCK RECIPES, V31 , D2 

If you change your mind, and want to alter or remove a LOCKed file named 
f , on the diskette In the specified or default drive, this command allows 
such a change* 



VERIFY f [,Ssl [,DdJ | t W) 
Example: VERIFY SAM 

Performs a check that the Information actually stored on the diskette in 
file f Is self-consistent. (Technically, this la what happens: When 
the file is created — with SAVE, BSAVE or WRITE ~ DOS calculates a 
checksum byte for the cootents of each output buffer and then stores that 
byte with the buffer's contents in a diskette sector. The VERIFTT command 
calculates a new checksum byte for the actual contents of each file 
sector, and compares it with the checksum byte originally stored with that 
sector.) If a file VERIFYa, no message is given; it's safe to assume the 
information on the diskette has been stored correctly. If a file does not 
VERIFY, the message 
I/O ERROR 
is presented. You may VERIFY any type of file* 



■ts 
■r~-a 

m- --a 

3 



=1 



s=sa 



HOH |<;| |,i| l,o) 

KtffWpltlM HOH 

HON G, I, 

All disk mmnmid* and all Information sent between the computer and the 
rilttfc utr iknrn.it ly not displayed on the screen. This command allows you 
to «nab1r iwnc or all of this display — a helpful tool when debugging a 
program. If C Is specified then disk commands are displayed. If t 
!■ specified, then information being sent from the disk to the Apple, as 
Apple's Input , will be displayed. If is specified, then information 
holng sent to the disk from the Apple, as Apple's output , will be 
displayed. 



At least one of the 

The parameters may 
prirnmetera appear only in the 



three para 
appear in 



ters must be present, 
any order, separated by 
commands MOH and tfOMGN. 



or MON is ignored, 
commas * These 



Nntrt HON remains in effect until a KOHON command, a change of language 
(KF or INT), a boot, or a restart (3D0G). Even RUNning a program won't 
cancel a HON* 



NHHOH |C1 |,I| (.01 

Examples: NOMOK C 

NOMON I, C 

Hie HON command enables you to display disk commands and/or Information 

sent between the computer and the disk: such information ia not normally 

displayed on the screen. The NOHON command allows you to disable some oi 

all of this display. The command 

KOHON C, I, O 

returns the system to its usual, default state* 

If C is specified then disk commands are not displayed. If I is 
specified, then Information being sent from the disk to the Apple, as 

Apple's Input , will not be displayed* If is specified, then 
information being sent to the disk from the Apple, as Apple's output , 

will not be displayed. 



UlSt 



At least one of the three parameters 

ignored. The parameters may appear 

These parameters appear only In the commands 



be present, or KOHON la 
in any order, separated by c 
HON and NOHON. 




HAXFI1.RS n 

Example: HAXFILE5 6 

ii In an integer from 1 to 16 that specifies the number of files that can 
hr active at one time. Uhen HAXFILES Is executed, 595 bytes of memory 
(called a file buffer) are reserved for each file* When you boot the 
system, n defaults to 3, so that you will have 1785 bytes reserved for 
fll> but f era and will be allowed a maximum of 3 files open simultaneously. 
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All DOS commands except PR*, IN* and HAXFILES require a file buffer. 
If you have HAXFILES 1, and one file is OPEN, an attempt to perform 
command (such as CATALOG) will cause the message 
HO BUFFERS AVAILABLE 
to be displayed. 



Thus 
DOS 






e 



s*a 



Use of HAXFILES moves H1MEM. This can erase Integer BASIC programs or 
Applesoft strings. Use HAXFILES b efo r e LOADing and RUNning a program. 
See the discussion in Chapters 5 and 7 it HAXFILES must be used from 
within a program* 



ACCESS COMMANDS 



FP [,Ss] UDdJ [,VvJ 

Example: FP, D2 

This command puts your system into Applesoft BASIC. Any Integer BASIC oc 
Applesoft program In memory is lost* If your computer contains the 
Applesoft firmware card, DOS uses that source for the language, regardless 
of the switch position oo the card. If your system does not contain the 
Applesoft firmware card, DOS attempts to load and run the program named 
APPLESOFT on the diskette in the specified or default drive. 

To place the APPLESOFT program onto a newly initialized diskette, first 
LOAD the APPLESOFT program from the Master Diskette, then (without RUNning 
or LISTing the file) SAVE APPLESOFT oo an Initialized diskette. You must 
use the name APPLESOFT for this file- 



x 



Do n« use RUN APPLESOFT to change languages. Everything looks fine at 
first, but DOS has not properly initialized th« Lttgoagfe* l*o wold the 
resultant mess, always use FP* 



INT 

Example: INT 



i 9 

■T:3 

B~ =1 
P =1 



This command puts the Apple into Integer BASIC, 
Applesoft program In memory is lost. 



CTRL-0 ( also written <CTRL>D > 

Example; 10 DS-CHR$(4) 

20 PRINT DS;"WRITE CHESS" 



Any Integer BA5IC or 
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Every character PRIHTed out by the Apple is first examined by DOS before 
it Is sent on to the outside world* If the Apple PRINTS out a RETURN 
character (most PRINT statements automatically end with a RETURN), and the 
no a I character ia a CTRL-D, this la a message to DOS that subsequent 
characters (until the next RETURN) are a DOS conmrnnd. Host DOS cocmands 
may be used from inside an Integer BASIC or Applesoft program. To do so, 
PRINT a string consisting of CTRL-D followed by the desired DOS command. 

iii.- recommended way to do this is to first create a string DS consisting 
only of a CTRL-D, and then to use BASIC statements such as shown in the 
example. Note the use of CHRS(M to create DS (this works only in 
Applesoft, since the CHRS function is not offerred In Integer BASIC). 
Instead, CTRL-D could have been typed inside quotation marks to create DS* 
but in this case no character is shown between the quotation marks* 

Every character sent out by the Apple ia first examined by DOS before It 
Is passed on to the outside world* If the Apple sends out a RETURN 
character (most PRINT statements automatically end with a RETURN), and the 
next character is a CTRL-D, this is a signal to DOS that subsequent 
characters (until the next RETURN) are a DOS command. A DOS 

PRINT statement whose first ouput 
separated from preceding and from 
For additional Information, see 
Appendix G* 



n program must appear In a 
CTRL-D and whose output Is 
printed output by RETURN'S, 
from within a Program", In 



comnand from 
character is 
succeeding 
"Use of DOS 



PR* s 
Example: PR* 6 

Sends subsequent Apple output to the device controlled from slot * & , 

Instead of to the TV screen* The command 

PR# 

returns output to the TV screen, if the command is used from inside 

programs, it must appear as a PRINTed DOS command, as shown below: 

10 D5- M "; REH CTRL-D 

20 PRINT DS; "PR# I" 

If no device controller card is installed in slot 9 s , the system may 

"hang" and you'll have to press the RESET key to recover 



INf s 

Example: IN# 6 

Takes subsequent Apple input from the device controlled from slot f s , 
instead of from the Apple keyboard. The command 

INI 

resetn the normal keyboard input* If the command is used from inside 

programs, it must appear in a PRIHTed DOS command, as shown below: 

10 DS- ,m : REH CTRL-D 

20 PRINT D$; "IN* L" 

IT no device controller card is installed in slot « a , the system may 

"hiing" and you'll have to press the RESET key to recover * 
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CHAIN f (,5s] I.Ddl [,Vv) 

Example: CHAIN PART TWO t Dl, 57 f VI* 

Used from within an Integer BASIC program, it loads and runs the Integer 
BASIC program named £ on the diskette in the specified or default drive, 
but does not clear the values of any variables. This means that program 

f can operate on the results of the previous program, and can leave datn 
for any following program. You cannot CHAIN Applesoft programs using this 
command: see the special procedure for Applesoft programs in Chapter 10 or 
Appendix G. 



SKMJBITIAL TEXT HUE COMMANDS 

OPEN f [,Ss] [,Dd] [,W] 
Example: OPEN SESAME, D2 

Allocates a oemory buffer of 595 bytes to the text file f , and prepares 
the system to write or read from the beginning of the file* This 
command is used with the WRITE and READ command* to create and retrieve 
sequential text files. 

If there is no file f on the diskette in the specified or default drive, 
one Is created. If a file named f is already OPEN, this command first 
CLOSES that file, before OPENing the specified file. 



CLOSE If] 

Example: CLOSE WINDOW 

If you were WRITEing, a CLOSE causes all remaining characters in the 
output part of the file buffer to be sent to the diskette specified when 
that file was OPENed. CLOSE f deallocates the buffer associated with the 
sequential text file f . If CLOSE is used without a file name, all OPEN 
files will be closed, with the exception of the EXEC file, (There can 
only be one EXEC file OPEN at any time- When another is implicitly 
OPENed, the existing EXEC file, if any, is automatically closed) 

If a program is interrupted by a CTRL-C while a text file is OPEN, it's a 

good idea to type 

CLOSE 

to keep any data from being lost. 



m s 
m * 

m ■■=! 

E =4 



X 



Files that have been allocated by an OPEN statement must be CLOSEd- 
Failur* to CLOSE a file that was OPENed and written to (by a WRITE) can 
result in loss of data- 



g =1 
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WRITE f [,Bb| 

Example: WRITE ADDRESS. DATA 

Alivr this command, PRINT statements send their output to the specified 
Hie Instead of to the Apple's TV screen. With the Byte parameter, 
WtlTElng begins at the b-th byte of the file <see Chapter 6, page 69). 
WRITE Is cancelled by the printing of any DOS command, or by an INPUT 
statement* The null DOS command (simply PRINTIng a CTRL-D) will do. 
WHITE must be issued In deferred-execution mode. 



x 



After this command all Apple output characters that would normally be 
displayed on the screen are sent to the diskette instead. This Includes 
INPUT question-mark prompts, error messages, and other unwanted 
characters. 



READ f |,Bbl 

Example: READ SESAME 

After this cosraand, INPUT statements (and GET statements in Applesoft) 
obtain their response characters from the specified sequential text file 
Instead of from the Apple's keyboard* With the Byte parameter, READing 

begins at the b*th byte of the file {see Chapter 6, page 69)- 

INPOT causes characters to be READ from the sequential file one field at fi 
time. A field consists of from 1 to 32767 characters, ending with a 
RETURN character. However, because of the limited capacities of strings 
and input/output buffers. It is very difficult to store and retrieve 
Fields of more than 255 characters. 

READ is cancelled by the printing of any DOS command. A null DOS command 
(Just PRINT a CTRL-D) will cancel READ. The READ command must be used in 
deferred-execution mode. 



APPEND f (,Ss] l.Dd) l,Vvl 

Example: APPEND WORE INFO 

This command opens the specified text file, but places the 
position-in-the-file pointer to the end of the file. After this 
command, the next character written into the file will follow the last 
nequentially written character presently in the file. An APPEND must be 
followed by a WRITE to the file of the same name. (APPEND must not be 
followed by OPEN, because OPEN will reset the position-in-the-f lie pointer 
back to the file's beginning.) 



159 



POSITION f [,Rp) 

Example: POSITION ADDRESS-DATA, R277 

POSITION places the posit ion-in-the-file pointer at the beginning of the 
p-th Held following the one you're In. A field 1* a sequence of 
characters terminated by a RETURN- Subsequent READs or WRITEs will 
proceed from that point in the file f. 

POSITION deals with a relative, not an absolute, position, since you count 
fields forward from where you are in the file when the POSITION is 
executed. 

POSITION actually scans forward through the contents of the file, 
character by character, looking for the p-th RETURN character. It then 
places the posltloo-ln-the-f lie pointer at the first byte following the 

p-th RETURN character. If, in this search, it finds any byte in which no 
character has ever been stored, the message* 
END OF DATA 

is given. Normally, this occurs when the p-th 
position in the file la beyond the file's last 



J 



field ahead 
entry. 



of the current 



EXEC f URp] l.Ss) [,Dd] [,VvI 

Example: EXEC UTILITY 

Similar to RUN, except that f Is a text (data) file containing BASIC and 

DOS commands as they would be issued from the keyboard* This allows you 

to set up files that can control the Apple, much as you would control the 
Apple yourself. 

There can only be one EXEC command in effect at a time- If the EXEC file 
contains the immediate-execution command EXEC, the original EXEC file is 
closed and the new EXEC file is opened and executed. If EXEC has OPENed a 
file, the command 
CLOSE 

will not CLOSE the file being EXEC'ed. When an EXEC file has completed 
all its commands. It CLOSES itself and stops. If a file being EXEC'ed 
contains a command to RUN any program, EXEC waits patiently until the 
program ends. Then the next conand in the EXEC file la executed* 



m 3 

^ =1 

W 3 

WE =J 

=J 
=3 
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However, if a program la running while an EXEC file is open, any INPUT 
statement In the program will take the next field from the EXEC file as 
the response. Ignoring the keyboard. Worse yet. If that response is an 
immediate-execution DOS command, the command will be executed before the 
program continues* 



x 



If you type CTRL-C to stop an Applesoft program that is running while 
EXEC file Is still open, the remaining commands in the EXEC file will 
usually not be executed. 



W =) 

e =1 



II ymi uprrlly the value of the R parameter, a position-in-the-file 
pointer la placed at the beginning of the p-th field in the file, and EXEC 
will utart executing from this point In the file. 

Am with POSITION* the R parameter used with EXEC should be thought of as 
Ihf Relative- Held position parameter. However, unlike POSITION, EXEC 
ujwoy* count n fields from the beplnnina of your file, so p Is always 
relative to 0. The other parameters work as usual* 

II you specify the value of the R parameter beyond the end of the file 
you'll get on 
RH» OK DATA 
menn/ige* 



RANDOM-ACCESS TEXT FILE COMMANDS 



OPEN F t i i USe] E,Dd) (»Vv) 

Example: OVEN SESAME, L2 

OI'EN allocates a 595-byt file buffer to the random-access text file 
and sets the record length to the number of bytes specified by j - 
mmber J mist be In the range i to 32767; j defaults to 1< 



f ■ 
The 



OPEN is used with the READ and WRITE commands to create and retrieve 
randow-accesa text (Ilea- Note that th* L (Length) parameter is not 
optional: by definition, you ttust specify the record length of a 
random-access text file. Each time you use a particular random-access 
text file, you must OPEN the file with the same L parameter value. DOS 
then uses that value to calculate the starting position of any specified 
record. 

If there is oo file f t one is created. 



CLOSE |f| 

Kiample: CLOSE BODE 



all remaining characters In 

sent to the diskette in tho 

de-allocatca 



If you were WRITE ing, a CLOSE causes 

output part of the file buffer to be 

that was specified when the file was OPENed. Ctf>SE 

buffer associated with the random-access text file 

without a file name, all OPEN files will be closed, 

an EXEC file. If any* 



the 
drive 
the 

r . If CLOSE is used 
with the exception of 



If a program 

good idea to 

CLOSE 

to keep from losing data. 



is interrupted by 
type 



CTRL-C while a text file is OPEN, it's a 
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Files that 
Failure to 
result In loss 



have been allocated by an OPEN statement mist be CLOSEd- 
CLOSE a file that was OPENed and written co (by a WRITE) can 
of datt. 



WRITE f (,Rr] [,Bb] 

Example: WRITE ADDRESS-DATA, R3 

After this statement, PRINT statements send their output to the specified 
file instead of to the Apple's TV screen. WRITE la cancelled by the 
printing of any DOS command, or by an INPUT command- The null DOS command 
(simply PRINTlng a CTRL-D) will stop a WRITE with a minimum of effort. 
WRITE can be used only in deferred-execution PRINT statements. 



The R (Record) parameter causes the WRITE to begin at the first byte of 
the r«-th record, where each record contains the number of bytes, J f 
specified by the L parameter given with OPEN. r defaults to 0* If 
the B parameter is specified, the WRITE will begin at the b-th byte of 
the r-th record in the file* 



® 



ill 



After the WRITE statement, 
normally be displayed on the 
This includes INPUT question-mark 
unwanted characters. 



Apple output characters that would 
screen are sent to the diskette Instead, 
prompts, error messages, and other 



READ f (,ftr] [,Bb] 

Example: READ SESAME, R3.B30 



After this statement, INPUT statements (and GET statements in Applesoft) 
obtain their response characters from the specified random-access text 
file instead of fcom the Apple's keyboard. INPUT causes characters to be 
READ from the random-access file's current record, one field at a time. 

A field can be from I to 32767 characters, ending with a RETURN character. 
However, no record should be more than ] characters in length, where J 
is the record length specified when the file was OPENed. 

The R (Record) parameter causes the READ to begin at the first byte of the 
r-th record, where each record contains the number of bytes, J , 
specified by the L parameter given with OPEN. r defaults to 0. If 
the B parameter is specified, the READ will begin at the b-th byte of 
the r-th record in the file. 

READ is cancelled by the printing of any DOS command. A null DOS command 
(just PRINT a CTRL-D) will cancel READ. 
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MACHME-LANGUAGC FILE COMMANDS 



HSAVE f. Aa, L] I ,Ss] [,Ddl [,Vvl 

Kxamples: BSAVE PICTURE, A16384, L6192 
BSAVE PICTURE, A54000, L52000 

Creates a file named f , and stores the contents of a segment of the 
APPLE II's memory. The segment is specified by the starting address a , 
and the number of bytes to be stored ] . 

The examples shown above store a high-resolution picture, from the second 
high-resolution picture area. They are operationally Identical: the 
second example just uses hexadecimal notation for the parameters* 



BUMP f [,Aa) [,Ss] I,Dd] f,W] 

Examples: BLOAD PICTURE, A8192 
BLOAD PICTURE, AS2000 

If a Is not specified, then BLOAD places the specified file in Apple's 
memory beginning at the starting location of the memory area that was 
originally BSAVEd. If a is specified, then the date Is placed in 
Apple's memory beginning at address * » Note that a machine-language 
program may no longer be executable if so moved. 

Assume that a a high-resolution graphics picture has been BSAVEd on a 
diskette under the file name PICTURE. Then the first example shown above 
would place the picture into the first high-resolution picture area, which 
starts at memory location 8192 (decimal). The second example la 
equivalent: the address is shown in hexadecimal, as Indicated by the "$ w 
before the 2000. 



t^ 



Either example would clobber any version of Applesoft that Is not in 
firmware. 



BRUN f I,Aa] [,SsJ [,Dd] l,Vv) 
Example: BRUN SUPER, A5C0A, V75 



BLOADs the file f Into Apple's memory beginning at location s . If the 
A parameter is omitted, the file is BlX)ADed starting at the same 
location from which it was BSAVEd. Once BLOADed, the file (which should 
be a machine-language program) is started by a machine-language Jump (JMP) 
to location a * 
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APPENDIX G 



OF DOS PROCEDURES 



tooting DOS 

166 IXltUllxl&g a Diskette 

166 Recovering (ran Accidental BESCTa 

166 Utft at DOS from within a Program 

167 Creating a Turnkey Syptem 

167 Creating and Retrieving Sequential Teat Vile* 

169 Adding Data to a Sequential Text Pile 

169 Gontroilios the Apple via a Sequential Text File 

119 Greeting and Retrieving ftando»*Acce»e Teat 

171 Copy log a Text File 

1/1 Chaining in Applesoft 








Thla appendix contains summaries of the main procedures used in DOS- Koch 
procedure is listed on the proceeding contents page, along with the page 
number on which it appears. 

BOOTING DOS 

Replace V by the alot number in which the disk controller is located. 



Prompt 
Character 

> 



Language 

Integer BASIC 

Applesoft 

Monitor 



To boot DOS, 
type 

PR#s or IN08 

PK#a or INJs 

s{CTKL}P 



INITIALIZING A DISKETTE 

To INITialirc a slave (memory dependent) diskette: 

1) Boot DOS 

2) Insert a blank diskette into the disk drive 

3) Type In a greeting program, e-g. 

10 PRINT "32K SLAVE DISKETTE INITIALIZED 5 MAY SB" 
29 END 

4) Assuming you choose to name the greeting program "HELLO", 
type the command 

INIT H&LO 

5) After the IN USE light on the disk drive goes out, remove 

the diskette and label It. 
To make a master diskette, use the MASTER CREATE progran, page 



RECOVERING FROM ACCIDENTAL RESETS 

If DOS has been hooted and dhen the RESET key is accidentally pressed, type 
3D*C 

(that's the numeral zero after the D) to get back into the BASIC you left 
with your program Intact. 



USE OF DOS FROM WITHIN A PROGRAM 

DOS commands may be Issued from within a program by PRINTIng CTRL-D then 
the command. First create a string DS which consists only of CTRL-D. 

In Applesoft, DS way be created by the command 

DS - CHR$<*) 

since CTRL-D is the character whose ASCII code ia 4. 



J 
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mm 
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■±sa 



In either BASIC, DS may be defined by typing 

DS - " 

then holding down the CTRL key while typing the letter D, and then typing 
UW closing quote. Control characters such as CTRL-D aren't displayed, so 
what you'll see is 
DS - *" 

This Applesoft program displays the CATALOG when RUN: 

B WSIt G*££T!NG PWKtffflh 

16 Prf * £3«* <4): K£H CTPL-P 

29 PR1KT £>*- "CRlflLOG" 
Only one DOS command may be contained in a single PRINT statement. The 
PRINT statement's quoted contents must begin with a CTRL-D and end with 
the DOS command. The CTRL-D must be preceded by a RETURN (sent 
automatically at the end of most PRINT statements). 

These commands should only be used in deferred-execution mode (from within 
a program), appearing after CTRL-D in a PRINT statement: 
APPEND READ URITE POSITION 



The commands INIT and HAXFILES are best used only in immediate-execution 
mode (not from within a program). 

Other DOS commands may be used either in immediate-execution mode, or from 
within a program where they appear after a CTRL-D in a PRINT statement- 



CREATING A TURNKEY SYSTEM 

To make a diskette that runs a certain program each time the diskette is 
booted — in the example we will use the program COLOR DEMO — use the 
following procedure: 

1) IRITialUe a blank diskette, using the name HELLO for the 
greeting program. 

2) Place a disk containing the COLOR DEMOS program In drive, 
and type 

RUN COLOR DEMOS 

Once you're satisfied the program RUN* correctly* return 

to BASIC. 

3) Put the newly INITialized diskette into your drive and type 
SAVE HELLO 

to replace the old greeting program by the COLOR DEMOS 
program. 



CREATING AND RETRIEVING SEQUBJTI AL TEXT FILES 

When creating a sequential text file, an OPEN must precede a WRITE; once 
WRITE Is executed, any subsequent PRINT commands send all characters to 
the diskette. CLOSE the file when you're done. A WRITE command is 
cancelled by an INPUT or the use of any DOS command in a PRINT statement 
— even Just PRINTing CTRL-D will do* 
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This Applesoft program creates a sequential toxt file named SAMPLE whoae 
first thirteen fields contain three strings and the Integers 1 through Id: 

5 R£H HAM SAMPLE 

i© r>« * cms (4J REM CTRL-0 
29 print p».. "open sflrtPtE- 

3© PRINT C»\. "DELETE SflHPLf 

49 PRINT P»- 'ORtN SHIPLE" 

50 PRINT D*> "WRITE SftTTlf 

68 PRINT "HI HO": PRINT -HZ HG" 
79 PRINT "OFF TO THE DISK HE AG" 

FOB J * 1 TO 1© 

PRINT J; NEXT J 
lie PRINT M- 'CLOSE 5HHPI.E- 



If you OPES a file that already exists and then WRITE to it, you will 
overwrite part of the original file. 

This Applesoft program retrieves the file SAMPLE described above, one 

field at a time. If you wish to sec what is being HEAD from the disk, the 

command 

HON I 

will cause Input froai the disk to be displayed. 



pen om*- 



5 REM RETRIEVE S* 
1© P* - CMR* 
IS CTRC-0 

PRINT Zr*A 'OPEN SflMPLr*' 

PRINT M-. "RERC- SRWPIX" 

INPUT A*.. B*. G* 

FOR I = 1 TO 10 

INPUT M 

NEXT I 

PRINT Ms "Ct-OSE SftNPUE" 



n 



7» 



An OPEN must precede a READ. Once a 
INPUT statements (in Applesoft, CETs 
characters from the diskette instead 
the file when you're done. 



READ is executed, any subsequent 

also) obtain their response 

of from the Apple's keyboard. CLOSE 



m h 

e -i 

* -i 
e -i 

•fa 



A READ is cancelled by PRINTing CTRL-D, whether or not it's followed by a 
DOS command * 






ADDING DATA TO A SEQUBtTIAL TEXT FILE 

This Applesoft program adds the two strings "TEST 1" and "AND HOW FOR TEST 
2" to the end of a sequential text file called SAMPLE. Each string is tn 

an additional field of the file. 



RPPtNP SrtHPUE 



CTRt_-[> 



a Ot, '■aPPENG StWLE" 
- Of. 'i*RIT£ SflHPtE" 

- . . . ■ i-» 

T "ftNf" r^ow FO* 
PRINT £•*■ -CLOSE SftMPLe" 



CONTROLLING THE APPLE VIA A SEQUENTIAL TEXT FILE 



When RUN, this Appleeoft program creates 

the eownanda 

LIST 29,50 

RUN HELLO 

CATALOG 



a text flic named DOIT containing 



5 REM MflKE ["OH 

X9 !>* - CWR» ■■:. «EM 






M PRINT C*. "OPEN DOIT* 

PRINT D*< 'fc*UTE DOIT" 

4tt PRINT "LIST 2ft, 5©** 

» PRINT -RUN MEti 

PRINT "V.hThlOu" 

,-0 PRINT C-*,- TLOS T- 

Once the text file DOIT is created, the command 

EXEC DOIT 

will cause the comraanda in the file DOIT to be executed one by one. Just 

as if they'd been typed in from the keyboard. 
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CREATING AND RETRIEVING RANDOM-ACCESS TEXT HUES 

This Applesoft program creates a random-access text file named RA-FILB, 
whose records are each 30 bytes long. Then it WMTRs the string "HAME 
ADDRESS" followed by the record number. Into records 12 through 15 of the 
file. In lines 70 and 80, record number 13 is changed to contain the 
string "DOS". 






REM 
PftJ 

HNT 

[NT 



ChW ■ A ■ *£M 



mu-t> 

&** "OPEN R&-FILC' 

;■■«, *cci.rrfi *ft-fSLE- 

C* 'OPEN *fl-FlLE>t3*" 

IS 
P* -WRITE Rft-FJlE.R* i 



14a 



PR If 



This Applesoft program READS records 12 through 15 of the random-access 

text file RA-FtLE. Note that you must specify each record before RFADing 

It in line 40. Line 60 examines the three leftmost characters of the 

input string AS, taken from each record. If those three characters are 
"DOS", the message "RECORD r WAS CHANGED." is PRIHTed, and the search 
continue**. 



5 
an 



8* 



RETfi F^-FILE 

V* -■ • I t* -•-- REM CTRL-* 
WUNT &*{ w OPEN PR-rii-E, L30" 

■ 



t 

* H 

■> "==1 
»T =1 

•4 
74 



ta^< 
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fli 



-fv 



I.F LEF 



THEN 



COPYING A TEXT FILE 

Moving a BASIC or a binary program file to another diskette la no problem: 
Juot LOAD or BLOAD the file's contents Into the Apple, and then SAVE or 
HSAVE those contents back onto the other diskette. Remember to specify 
thf starting address and length parameters when using the BSAVE command. 

The COPY program allows you to bulk copy the contents of one diskette onto 
another- If any of the files on the original diskette are protected fro* 

copying, you'll get an error message: 

T/O ERROR 

STOPPED AT 320 

To copy a text file, or any unprotected file for that matter, use the FID 
program* The full instructions for using FID are in Appendix J. 

CHAINING IN APPLESOFT 

To REN a series of Applesoft programs without erasing earlier values of 
variables and arrays use the following procedure* 

Suppose you wish program PART ONE to chain to the program PART TWO* 
First, make sure the binary file CHAIN is on the same diskette with the 
program PART TWO. {If it isn't, use FID to copy It onto the right place.) 
Then simply insert these two lines as the 
last two lines to be executed in the PART ONE program: 
PRINT CHR$<4); "BLOAD CHAtN 1 A520" 
CALL 520" PART TWO" 

No space or other character may be between the 9 and the " 
in the CALL command* 
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If you already have a Disk Operating System, and are usinft *i version of 
DOS that runs in 13 sectors, (DOS 3*2*1 or earlier), you will need to 
change two prons on your disk controller card to update your system to 16 
sectors- Any version of DOS earlier than release 3-3 will need to be 
updated- 

HOW TO INSTALL THE NEW PROMS 

The new disk controller PROMs replace two PROMs on each Disk II controller 
card in your Apple. 

Inside the case, find the edge-connector "slots" at the rear of the main 
board- In one or more slots you will find cards labelled 'Disk II 
Interface Card' at the top edge* Hake sure the power is off* Remove each 
of these controller cards by grasping it at the top edge and gently 

rocking it back and forth. Remove the ribbon cables from each card, so 
you can work on it more easily* 

Hold a controller card in one hand. IC side toward you, "fingers portion" 

down* You will see four rows of two ICs on the card. Find the left IC in 
the second row from the top. It should be marked 'P6* or *3M-Ml0-xx* 
(possibly under a copyright sticker), and the card below it should be 

marked 'PROM P6'. This is the IC you will replace with the new PROM P6A. 



4* 

* -I 
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m -t 
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Now find 

0009- xx 

should be marked 'PROM P5'. This is the IC you will replace with the new 

PROM P5A. 



the left IC in the bottom row. It should be marked 'P5' or '341* 
(possibly under a copyright sticker), and the card below it 
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Now look at the new PROMs. The new PROM P6A should be marked 'P6A' or 
*)M-f028-xx', or both- The new PROM P5A should be marked 'P5A' or '341- 
0027'Xx', or both. You should be able to find these markings without 
pet-ling off any stickers. If you can't find the numbers at all, see your 
dealer. 

Now that you know where everything Is, you are ready to replace the old 
PROHs with the new ones* Set the controller card down on a table and hold 
it firmly* Using the IC puller, gently remove PROM P6 from its socket. You 

may find a transistor, marked 'Q3' on the card, blocking the IC puller- If 
no, gently bend it out of the way until It is approximately vertical- 
Grasp the IC with the puller, and gently rock it out of its socket. 

Hold PROM P6A, marked 'P6A' or ' 341-0028-xx', so that it faces the same way 
as the ICs on the card. The large rectangular notch should be on the left 

side as you face the card* (There may be a small circular depression on 
the other end- If you are not sure which end goes where t ask your dealer*) 
Making sure that each pin lines up with its hole, gently Insert PROM P6A 

into socket P6. If the pins are too widely spread to go in easily, you may 

have to bend them in until they are vertical, by pushing them carefully 
(gentlyl) against a table top. 

Now remove PROM P5 and replace it with PROM P5A, marked 'P5A' or '341-0027- 
xx' f Just ss you replaced P6 with P6A. 

If you have more than two Disk II drives, you will need one controller card 
for each two drives. Each of these cards will need the new PROMs* Install 
these as you installed the first pair. 

MULTIPLE DISK DRIVES 

Now connect each Disk II drive to its controller card and plug the card 
Into Its slot, in the order shown in the table below* The first drive 
should go in the first location listed (slot 6, drive 1), and so forth, 
until you have Installed all your drives. You will be working downward 
from slot 6, filling first the drive 1 and then the drive 2 connectors of 
each card. This will ensure that the drives are in the most efficient 
locations, and will increase the reliability of your system: programs will 
not try to use drives that are not there, or Ignore drives that are there. 



Placement of Disk II Drives 



Installation 


Order 


1st 


drive 


2nd 


drive 


3rd 


drive 


4th 


drive 


5 th 


drive 


6th 


drive 



Slot No- 



Drive No, 



1 
2 

1 
2 

1 
2 



Label each drive 'DRIVE 1' or 'DRIVE 2', as appropriate. 
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Check that all connections are secure and that everything has been 
Installed In its proper place- PROM P5 of each controller card should 
have been replaced by PROH PSA (3M-0027-xx). PROM P6 of each controller 
card should have been replaced by PRCW P6A (341-0028-xx). A Disk 11 
ribbon cable should be plugged into the drive 1 connector of each Disk II 
controller card* Slot 6 should have a controller card* 



you can 
sector 



When you are satisfied that everything is installed properly. ; 
replace the Apple's cover and go on to update your existing 13 
diskettes to 16 sectors* using MUFFIN. 

USING DOS WITH THE LANGUAGE SYSTEM 

You can use DOS and both Applesoft and Integer BASIC with the Apple 
Language System installed. You do not need the BASICS Diskette to do this. 
To begin a 16 sector DOS after using any language on the Language System 
which uses the Pascal Operating System, follow these steps: 

1) Be sure to save any program you have been working on. Otherwise, it 
will be erased from memory when you begin DOS. 

2) Get into the Command mode of the Pascal Operating System (so that you 
can see the line which begins with "Command:")* 

3) Replace the diskette in your Drive 1 (connected to the controller card 
in your highest numbered slot) with the DOS System Master diskette- 

4) Type H (for Halt)- This will cause that disk drive to boot your System 
Master diskette. 

Your System Master diskette will now load either Applesoft or Integer BASIC 
— whichever is NOT already available on your main board ™ Into the 
storage space available on your Language Card. If you have a standard 
Apple II, the System Master, when booted, will load Applesoft into your 
Language Card. If you have an Apple II Plus, Integer BASIC will be 
loaded* In either case, a message will appear, telling you which BASIC is 

being loaded during the booting of your System Master. All of the DOS 
commands will now work in the using and writing of programs in both 

Applesoft and Integer BASIC. 
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To learn the procedure for starting 
NOT use the Pascal Operating System, 



DOS after using a language which does 
see the manual for that language* 



With the Language System installed, you can boot DOS upon turning on your 
Apple, with the System Master diskette in Drive 1. 

To return to another Language System language from DOS, replace the System 
Master in Drive I with the startup diskette for that language- Then type 
PRJ6 and press RETURN. 
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SETTING UP A TURNKEY SYSTEM 

When you insert a DOS 3-3 diskette in drive 1 and turn on the power, your 
Apple will run the HELLO program on that diskette, if it has in RCH the 
BASIC In which the HELLO program Is written- That Is, an Apple II will run 
an Integer BASIC HELLO program, an Apple II Plus will run at\ Applesoft 
HELLO program, and an Apple II with the Applesoft Card or an Apple II Plus 
with the Integer BASIC Card will run a HELLO program in either BASIC* If 
you don't have that BASIC in ROM, you will get a 
LANGUAGE NOT AVAILABLE 
error message and the prompt for the BASIC It does have. 

If you have the Apple Language System, things get a bit more complicated. 
Without further ado, you can run programs in the BASIC in ROM, but before 
you can use the other BASIC, you must load it into the Language Card. The 
simplest way to do this Is to boot the DOS 3-3 System Master Diskette, 
which is provided with two programs, HELLO and APPLESOFT, that together 
make sure that both BASICs are loaded when you boot DOS. HO-LO, written in 

Applesoft for the Apple II Plus, loads Integer BASIC. APPLESOFT, written 
in Integer BASIC for the Apple II, loads Applesoft. Your machine will run 
the appropriate program, and afterwards behave as If It had both BASICS in 

ROM. You can now insert any other DOS 3<3 diskette, and run any program on 
it. 

If you wish to make a diskette that will boot on all systems, 

and load the Language Card If necessary, you can do it by copying the 

appropriate files onto It- Here's how: 

1. Boot the DOS 3*3 System Master Diskette. 

2. LOAD HELLO from the System Master, then insert a blank diskette and 
type 

INIT HELLO 

3. When INIT Is finished, reinsert the System Master, BRUN MASTER 

CREATE and type 

HELLO 

when asked for the name of the greeting program. Insert the blank 

diskette when told to do so by MASTER CREATE. 

4. Using FID, copy these files onto your newly Initialized diskette: 
APPLESOFT 

1NTBASIC 
FPBASIC 

5a Put any programs and other files you want on this diskette. Make 
sure you have at least the following files: 
HELLO 
APPLESOFT 
INTBASIC 
FPBASIC 

When you boot this diskette on an Apple with the Language Card, it will 
load the Language Card with the BASIC not in ROM, so that the Apple can 
run any program in cither BASIC* 
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If you have a turnkey progran you want the Apple to run when It Is turned 
on, you can do it by changing the HELLO and APPLESOFT programs so that each 
of them will run your turnkey program (we'll call it TURNKEY here)* You 
will find it easier to edit these programs if you first RUN LOADAPA. then 
use the &S command, so that you can see the CTRL-D In each embedded DOS 
command - 



Start with 
following: 



the diskette you have just made in steps 1 to 5 f and do the 



± 



6. UNLOCK HELLO 

7. LOAD HELLO 

8. LIST It and look at the last few lines 
240 END 

250 RBI 

260 REM —NO CARD OR CAN'T RELOAD 

270 RW 

280 IF PEEK (768) - THEN END 

290 PRINT: PRINT "...LANGUAGE CARD CANNOT BE RELOADED": 

PRINT " UNTIL THE SYSTEM IS REBOOTED..." 

300 END 

On the screen, the lines will be wrapped at 

they are broken elsewhere for clarity. 



=4 



characters; here 



Change these lines so they read as follows: 
240 GOTO 300 

REM 

REM —NO CARD OR CAN'T RELOAD 

REM 

IF PEEK (768) - THEN 300 

PRINT: PRINT "...LANGUAGE CARD CANNOT BE RELOADED": 

PRINT " UNTIL THE SYSTEM IS REBOOTED..." 

PRINT "ctrl-dRUN TURNKEY" 



250 
260 

270 
280 

290 



I i 



* 300 



The lines changed or added are i 
Ctrl- d in line 300 represents 
screen or in a listing* If you 
In your files, you can declare 



larked with asterisks. The lower case 
i CTRL-D which won't show up on the 
don't like invisible control character! 
i string DS containing a CTRL-D, which 






would make line 310 look like this (in Applesoft): 

318 DS-CHR$(M : PRINT D$;"RUN TURNKEY" 

If you do this, make sure you declare DS before you 



use it* 



You may also wish to change or delete some of the PRINT statements in 



the program, but 
will have CTRL-D 

10. SAVE HELLO 

11. LOCK HELLO 



make sure you leave 
i in them) • 



the ones with DOS commands (those 



12. UNLOCK APPLESOFT, LOAD It, and LIST it, looking at the last few 

lines* 

250 GOTO 310 

260 REM 

270 REM — WO CARD OR CAN'T RELOAD 
280 REM 

290 IF PEEK (768) - THEN 310 

300 PRINT "...LANGUAGE CARD CANNOT BE RELOADED 11 : 

PRINT " LWTIL THE SYSTEM IS REBOOTED..." 
310 PRINT "ctrl-dINT" 

13. Change these lines to read as follows: 
250 GOTO 310 

260 REM 

270 REM —NO CARD OR CAN'T RELOAD 
280 ROl 

* 290 IF PEEK (768) - THEN 310 

300 PRINT "-- .LANGUAGE CARD CANNOT BE RELOADED": 
PRINT " UNTIL THE SYSTQI IS REBOOTED.,." 

* 310 PRINT "ctrl-dRUN TURNKEY" 

Line 310 can also be put In the for* 

* 310 D$*"ctrl-d":PRINT D$;"RUN TURNKEY" 
to nake the CTRL-D easier to find. 

U. SAVE APPLESOFT 

15. LOCK APPLESOFT 

16. RENAME your turnkey program TURNKEY. A sample TURNKEY program. In 
Applesoft* Is below: 

100 TEXT : HOME 

110 VTAB 3: PRINT "DOS TOOL KIT "; TAB( 30) ;"30 NOV 1979" 

120 VTAB 5: PRINT "(C) COPYRIGHT 1979, APPLE COMPUTER INC." 

130 FOR I ■ 1 TO 1500: NEXT I 
140 PRINT "ctrl-dRUN RIBBIT" 

17* Make sure your diskette has the following files on it: 
HELLO 
APPLESOFT 
INTBASIC 
FPBASIC 
TURNKEY 

18. Now test your turnkey diskette by putting it in drive 1 and 

turning the power off and on. It should boot DOS 3-3, then load 

Integer BASIC or Applesoft if necessary, then run the program 
named TURNKEY, 
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The "BASICS" diskette that cane with the DOS system master can be used to 
boot i:!-si3ctoc diskettes on your 16-scctor systea* Versions of DOS 
earlier than 3-3 are 13-sector DOS. 

Apples coi&e In two flavors: Apple II and Apple 11 Plus- The Apple II has 

Integer BASIC In Read-Only Memory (BOM) on the main printed-clrcuit bo/ird. 
The Apple II Plus has Applesoft BASIC in ROM on the main board. The 
language In ROM Is the language the Apple will come up in when It is turned 
on. If It has no disk drives or accessory cards. 

BOOTING DISKETTES USING "BASICS" 

To use either Integer or Applesoft BASIC* Insert the "BASICS" diskette into 
the drive, and turn the Apple on* In about five seconds the screen will say 

iHsun vour ta-secKW diskette 
pm press k«tue* 

Insert any 13 sector DOS/BASIC diskette and press RETURN . The Apple will 
now behave as described in this Manual, except that one step Is added to the 

boot (startup) procedure; 

Vhen you turn the Apple on, or type PR#6, 1NJ6, C600G, or 
6CTRL-P, the "BASICS" diskette nust be in the drive, each tis* 
you want to boot a 13 sector DOS. 

When the cue comes on the screen, insert the 13 sector DOS/BASIC diskette you 
wish to boot* If you are in either BASIC and you type PR#6 or INI6 , you 
will have to insert "BASICS", then reinsert your previous diskette. 

Once you have DOS running, you can switch from one BASIC to the other by 
using the INT and F? cosnuands normally* 

As always, you can tell which BASIC you are In by the proapt you sec on the 
acreen: > for Integer BASIC and 1 for Applesoft BASIC. 

A diskette designed for "turnkey" operation (that Is, one that starts 
executing a program when booted) can be run as before, after the "BASICS" 
diskette has been run- 

You can reboot DOS without turning the power off. Sl*ply Insert "BASICS", 
type PR#6 or IH#6 and press RETURN , then at the cue Insert the 
diskette you wish to boot* 
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FID (for File Developer) extends the abilities of 16-sector DOS In two 

ways* First* It lets you easily catalog, copy, delete* lock, and unlock all 
types of DOS files* Second, it lets you copy from one diskette to another 
with only one disk drive* 

FID runs on any Apple with Applesoft* 32K or more of memory, and one or 
more Disk II drives* The FID destination diskette (the one you will be 
copying to) must be INITialized in order for FID to work- 



STARTING UP 



To use FID, boot the DOS System Master Diskette. 
BRUS FID 



then type 



You will see a list of commands on the screen* Each of them can be 
executed by typing the number in angle brackets < >* 

FILENAMES AND WILDCARD CHARACTERS 

Some of the commands ask you for a filename* The filename is typed just 
as for a DOS command, except that you can replace part of the filename 
with the '"wildcard" character ( * )• For example, if you typed the 
filename 

FR-ED 

the program would select all the files whose names began with 'FR' and 

ended with *ED*. If you typed 

all files whose names contained *N* would be selected. If you typed 

all files on the diskette would be selected. ("On which diskette?", you 
night ask. This will be explained below.) 

If you used a wildcard character in a filename specification, you wilt be 
asked 

DO YOU WANT PROMPTING? 

If you reply by typing 

Y 

for Yes, you will be asked to verify each filename before it is acted on. 

If you want the file, when the system displays It on the screen, typo 

Y 

If you don't want the file, type 



E -4 

e -« 

e -4 



■? 4 

e i 

E 4 



m 4 
m 4 

■e 4 



m * 



m 4 

E -4 



In either case, you will then be prompted with the next fllenane matching 
your specification* 

If you don't want the file or any of the rest, type 

Q 

and no more files will be acted on. 

If you reply 

N 

to the 'DO YOU WANT PROMPTING?', all files matching your 

opacification will be selected. 

COMMANDS 

Host of the FID commands — Catalog, Space, Delete, Lock, Unlock, and Verify-* 

operate on one drive: the one last used, unless the defaults are reset. 
The Copy command can use one drive or two, as you wish* The Quit command 
does not use the drives: it simply exits the program, leaving you in DOS. 



When 

your 

Delet 

numbe 

first 

slot 

Any t 

will 

can c 
FID t 



the program first comes up, no default drive will have been set* If 

first command is one of the one-drive commands — Catalog, Space* 

e. Lock, and Unlock — you will be prompted for a slot and drive 

r* These will set the default drive until they are changed* If your 

command is the Copy command, you will be prompted for two sets of 
and drive numbers, one for the source and one for the destination* 
ime you switch from Copy to a one-drive command, or vice versa, you 
be asked to specify one or two drives* With the Reset command, you 
ancel the default slot and drive numbers at any time, which will cause 
o prompt you for new ones when it needs them. 



Note; make sure you give real slot and drive numbers: if the Apple tries 
to read from or write to a nonexistent drive, the program will crash. 

CATALOG 



Typing 

2 

gives you a catalog of the default diskette. If you have not set the 

defaults, you will be prompted for slot and drive numbers* Once these 

have been set, all commands will automatically refer to this drive, unl 

the defaults are reset. 



RESET SLOT AND DRIVE 

The Reset command lets you change the default slot and drive* To use it, 

type 

J 

This cancels the current default slot and drive numbers. The next time you 

give a command that requires slot and drive numbers, you will be prompted 
for them. This command is convenient if you wish to Catalog two drives in 
succession- 
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Note: The Reset Slot and Drive command should not be confused with 
the RESET key . They will always be capitalized differently, to avoid 
confusion* 



LOCK FILE 



To lock a file, type 
5 

and, when prompted, type the filename. If you type an Invalid filename, 
you will be prompted until you give a valid one* 

You will now be asked to Insert the diskette containing this file, and 
asked whether you wish to ESCape or proceed. If you proceed and the file 
is on the diskette inserted, it will be locked. When you catalog the 
diskette, the filename will be preceded by an asterisk , * B indicating 
that the file is locked. If the file is not on the diskette, you will get 

a NO FILES SELECTED error Message: you can recover by pressing any key 
except RESET. SHIFT, CTRL, or ESC. 



UNLOCK FILE 



To unlock a file, type 

4 

and, when prompted, type the filename 

you will be prompted until you give a 



If you type 
valid one* 



an Invalid filename. 



You will now be asked to Insert the diskette containing this file, and 

asked whether you wish to ESCape or proceed. If you proceed and the file 

Is on the diskette, it will be unlocked. When you catalog the diskette, 
the filename will not be preceded by an asterisk , * » indicating that the 



file is not locked. If the file Is not on tin 
FILES SELECTED error message: you can recover 
RESET, SHIFT, CTRL, or ESC 



i diskette, you will get a NO 
by pressing any key except 



VERIFY 

The Verify command is the same as the DOS VERIFY command, and handles all 

types of files. To use It, type 

6 

and answer the prompts. When a file has been verified, the screen will 

display its name and the word 

DONE 

If a file can't be read and is thus invalid, you will get an I/O ERROR 
message, and the program will prompt you to press a key. When you do so, 
you will return to the main menu* 
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COPY FILE 

FID can Copy files on either a multiple-drive or a single-drive system. To 

Copy files, type 

I 

and you will be prompted for Source slot and drive numbers, then 

Destination slot and drive numbers. 

Unit lple-Drlve Copying 

If the slot and drive numbers are different, you will be asked for a 
filename, which can contain wildcard characters. You can copy a whole 
diskette hy typing » in response to this prompt. After you have given the 
filename, you will be asked to insert the appproprlate diskettes and press 
either ESC, to abort the Copy, or any key but RESET, SHIFT, CTRL, or ESC, 
to go ahead. If the files you asked for are on the source diskette, and if 
there Is enough room for them on the destination diskette, then you will be 
Informed that your file has reached its new home; otherwise, you will get a 

DOS error message* 

If the destination diskette already contains a file with the name you 
used, you will get the message 

FILE 

ALREADY EXISTS. 
TYPE IN NEW FILE NAME FOR THE COPY OR 

<RETVRN> TO REPLACE PRESENT FILE OR 
<CTRL-C><RETURN> TO CANCEL COPY 

: 

If you enter a new filename, the file will be transferred and stored under 

that new name* If you press RETURN, the old file will be replaced by the 
new one, if the old file is not locked. If it is, you will see 

FItE LOCKED. 

DO YOU WISH TO REPLACE IT ANYWAY? 

I f you type 

Y 

the file will be replaced; if you type 

N 

you will get this message again: 

FILE 

ALREADY EXISTS. 
TTP8 IN NEW FILE NAME FOR THE COPY OR 
<RKTIfRN> TO REPLACE PRESENT FILE OR 
<CTRL-CxRETURN> TO CANCEL COPY 
I 
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If, when you see this message, you press CTRL-C and then RETURN, the file 
will not be copied- If no files were found to copy, the program will print 

NO FILES SELECTED 

If a file was found, the program will print 

DONE 

Then you will be prompted: 

PRESS ANY KEY TO CONTINUE 

Pressing a key will return you to the menu* 

Sinale-Drlve Copying 

If the specified slots and drives for the source and destination are the 
same, the program will tell you when to put the source and when to put the 
destination disk into the drive- Thus, copies can be made between two 
disks with only one drive. 

DELETE FILE 

This command deletes a file or set of files from the default diskette. 

To use it, type 

6 

You will be asked 

FILENAME? 

When you type the filename, the program will try to delete the named 
file. If all goes well, you will see the message 

<DONE> 

on the screen* If the file could not be found, you will get the message 

NO PILES SELECTED 

If the file was locked, you will get the message 

FILE LOCKED 

and the file won't be deleted. 

To return to the menu, press a key other than RETURN, ESC, CTRL, SHIFT, or 
RESET when you see the prompt 

PRESS ANY KEY TO CONTINUE 
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SPACE ON DISKETTE 

This command lets you find out how many sectors are used, and unused, on 

thr default diskette. To use it, type 

3 

and those numbers will be displayed on the screen. 

QUIT 

This ccwaand lets you exit the program cleanly. When you type 

you will see the same prompt on the screen as you saw before you ran FID. 

ERROR HANDUNG 

If the program detects an Irrecoverable error, it will display an error 
message and abort the operation. If a Copy operation is aborted, you 
should catalog the destination diskette and delete any spurious file that 
may have been created by the operation. This spurious file, if it exists, 
will have the name of the original file, or a new filename if you gave it 

one, but it will be shorter than the original file, as it will be 
Incomplete* 

Error messages are generated for these errors: DISK FULL, DISK WRITE 
PROTECTED, FILE LOCKED and I/O ERROR. If one of these occurs, FID will 
wait for you to press a key, then return you to the main menu* 

If a DOS error other than one of these occurs, its error code number will 
he printed. This will happen only if you clobbered DOS, or clobbered FID, 
or tried to copy a BAD FILE. If any of these things happened, you should 
reboot DOS, and reBRUN FID. 

If an error causes a spurious file to be placed on your destination 
diskette, delete that file immediately, before copying any other files to 
t ho destination diskette. 
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The current DOS is a "16 sector" DOS* Earlier versions of DOS Are 13 

sector- For a discussion of sectors, see the section entitled "Overview of 
the Storage Process" in Appendix C. 

A 16 sector DOS wilt not work with diskettes that have been INITislized 
with a 13 sector DOS* This Is because the information Is arranged 
differently on a 13 sector diskette* If you try to use 13 sector diskettes 
with a 16 sector DOS. you'll see the message 
UNABLE TO READ/WRITE 

STARTING UP 

The MUFFIN program converts 13 sector diskettes, and the programs they 
contain, to 16 sector* It does this by rearranging the information and 

then writing it onto another diskette* The diskette it writes the 
information onto (the "destination") oust have been initialised with a 16 
sector DOS. After the information fro* the old diskette (the "source") is 

converted onto the destination, the 13 sector version of it will still 
exist on the source diskette- 

To maximize the amount of disk space which is usable by this DOS, It's beat 

to convert all your 13 aector files to a 16 sector diskette and then re- 
initialize the old diskettes with the current DOS* 

The MUFFIN program will work with either one or two disk drives- 

this example shows how to use MUFFIN to convert files from a 13 aector 

diskette onto a 16 aector diskette, on an Apple with one dink drive* It 
assumes your disk drive Is connected to the controller card in slot #6* 

1) Place the System Master diskette in your drive and type 
BRUH MUFFIN 

2) When the message 

m PFPIX ff DOS 3 2 TO CS. 3 CONVERTER * 

* * 

* MUFFIN VERSION D ♦ 
+ * 

* C0PVR1GMT 1979 RPFLE COMPUTE* INC * 

CHOOSE 0« OF THE FOLLOWING GPTIOWS 

<1> CONVERT FILES 

<2> QUIT 
WHICH WOULD VOU LIKE? 



appear*, type 

1 

to Indicate chat you wish to convert files* 






E 






H 
H 

i 
J 

< 

4 



To the 



3) Now you'll see the question 

SOURCE SLOT? 

Type 6 (the number of the slot your disk controller cord Is in)* 

next question: DRIVE? respond with 1. 

*) When you see 

DESTINATION SLOT? 

type 6, and then answer the question DRIVE? by typing U 

5) Now you'll be asked for the name of the file to be converted: 
FILENAME? 

Type - (an equals sign) here* The ■ is a symbol which represents the 
names of all the source diskette's files* This response means that you 
wish to convert the entire contents of the source diskette. 

6) Before anything will be converted, you'll see 

DO YOU WANT PROMPTING? 
For now, type H for No* 

7) When you see 

INSERT DISKS THEN PRESS <ESC> TO RETURN TO 
MAIN MENU OR ANY OTHER KEY TO BEGIN 

reaove the System Master diskette fro© the drive and Insert a 13 sector 
diskette containing files you wish to convert to 16 sector. Then press 
RETURN - 

8) After the message 

INSERT SOURCE DISK AND PRESS A KEY 
appears, simply press RETURN* 

9) The program will now find the first file on your 13 sector diskette 
and print its name* Then It will stop and wait for you to replace that 
diskette with a 16 sector <IN ITialized) diskette- Do this and press 
RETURN. 

You'll see 

DONE 

when the file has been converted. Then you'll he Instructed to re- Insert 

the source diskette- Repeat this procedure until all your 13 sector 

files have been converted Into 16 sector files. 



Note: To convert large files, you 
for to get whole file transferred. 



ray need to swap diskettes several timen 



When you are converting files using more than one disk drive, specify the 
slot and drive nuabers of the source and destination diskettes when the 
program asks for them (steps 3 and * above)- Place the diskettes in the 
appropriate drives (step 8) before the conversion begins. 

When you see the message 

INSERT DISKS THEN PRESS <ESC> TO RETURN TO 

MAIN MENU OR ANY OTHER KEY TO BEGIN 

you have the chance to change your mind about converting the file- If you 

press ESC here, the program will stop In its tracks and send you back to 

the menu- 
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If you try to convert a 13 sector file with the 
already on che destination diskette, you'll ace: 



same name as 



a file 



PILE [filename] 

ALREADY EXISTS. 
TYPE IN A NEW FILE NAME FOR THE COPY 
OR <RETURH> TO REPLACE EXISTING KILE 
OR <CTRL~C><RETURN> TO CAKCEL COPY: 

At this point you may either (a) type a new nan* for the file to be 
converted, (b) convert the 13 sector file and have It replace the file 
currently on the 16 sector destination under that name or (c) type CTRL-C 
and press RETURN to halt the conversion- 



USING WILDCARD CHARACTERS 



As you saw in the example, * nay be used to mean "all files on the 

diskette". The » may also stand for any character or group of characters 

within a filename* For example, if you respond to the question 

FILENAME? 

by typing 

FI-LB 

you will convert all files on the 13 sector source diskette whose names 

begin with FI and end with LE. In the same way, -TEXT converts all files 

whose naaes end with TEXT and -*■, all files with names containing an 



E 

eg 

e = 

*-■ - 

E 1 



INDICES 



1M 



rrofrn I odea. 
2* Mui M t lod«* 
ta*14* ftftefc C*v«rt 




*. 



Because the ■ acts like a wild card in a card game It's called the 
"wildcard character". 

The question 

DO YOU WANT PROMPTING? 

will appear when you use the wildcard character. If you respond with Y 

here, the program will atop after finding each file on the 13 sector 

diskette and wait for you to indicate whether or not to convert that file 

(by typing Y or N, or Q to stop and return to the menu). A response of N 

to 

DO YOU WANT PROMPTING? 

indicates that all the flies In the wildcard group should be converted. 
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GENERAL INDEX 

Also see the PROGRAM INDEX and 

Inside the Manual's back cover 
PROCEDURE SUMMARY INDEX. 

-A- 



a: see A (address) parameter 

A-register 94-95 

A (address) parameter 92, 1 50 

with BLQAO 93 

with BRUN 93 

absolute byte parameter 69-70 
125 

absolute-field position 

(R) parameter 79 
address field 94 
address (A) parameter 92, 150 
analog board schematics 146 
APPEND 66-6 7 f 159 
Apple II BASIC Programming Hanual 

10 
Applesoft BASIC 28-29 
Applesoft II BASIC Programming 

Reference Manual 10, 48 
Applesoft firmware ROM card 107 
APPLESOFT program 29 

-B- 

b: see B (byte) parameter 
B (byte) parameter 

with READ 69-71, 89, 150 
with WRITE 69-71, 89, 150 
backing up 37-38 

BASICS diskette 182 

binary files 92 

BLOAD 93, 163 

booting 11-12, 166 
13 sector 182 

BRUN 45, 93, 163 

BSAVE 92,163 

byte (B) paraMETER 6W1 



the MESSAGE INDEX at the end of this section^ 
is the COMMAND SUMMARY INDEX and the 



-c- 



C, control 18, 39 

C (command) parameter 
with MON 42 
with NOMON 42 

cable 2-4 

CALL -151 29 

CALL -868 43 



15, 25 
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42 
30, 



151 



cassette tape recorder 

CATALOG 16, 152 
CHAIN 106, 158 

chaining in Applesoft 
CHRS(4) 30 
CLOSE 158, 161 

command (C) parameter 

control character 17, 

controller card 2-4 

CONTACT 2 

COPY program 38-40 

COPYA program 38-40 

copying 

diskettes 38-40 

programs 15-16 

text files 134 
CTRL (control) 11, 148 
CTRL-C 18, 39 

CTRL-D 29-31, 156-157, 166 
CTRL-K 103 
CTRL-P 103 

-D- 



d: see D (drive) parameter 
DS 30 

D f control 29-31, 156-157, 166 
D (drive) parameter 22, 149 
data field 94 
data files: see text files 
debugging 42 
default values 22 

deferred-execution mode 29-31, 48 
DaETE 18, 26, 154 
device characteristics table 
94-98 



E 
E 
E 
■ 



■4 
•4 

-4 
-4 
•4 
4 
4 



4 
•I 

4 
•1 

>l 



disk(ette) 








care of 5-6 








CATALOG 16, 


152 






directory of 


sector 


format 


129-131 








format 94 








INITiallzlng 


13-14, 


, 18, 


166 


Insertion and 


. removal 6- 


*7 


storage 1 24 








volume rtUBtoei 


23 







J 

J 
=1 



disk drive 

care 5 

installation 2-4 

multiple drivea 5, 22 

troubleshooting 12 
DISK FULL 120 

display options: see MON, NOMON 
DOS (Disk Operating System) 

command summary 110-111) 
148-164 

commands from within a program 
31, 166 

input, output registers 
101 * 104 

memory usage 140 

messages 114-122 

procedure summary 165-171 
drive option: see drive parameter 
drive (D) parameter 22 
duplicating disks 38-40 

-E- 

END OF DATA 117 

erasing files 18, 26, 154 

error codes 114-115 
error messages 114-122 

also see MESSAGE INDEX 
ESC (escape) 11, 149 
EXEC 74-79, 160-161 
EXEC files 75 

creating 75 

-F- 

FID 184-189 
field 51, 124 

field (R) parameter 
with EXEC 79 

with POSITION 67-69 
file 16 

data: see text 

EXEC 74 

machine language 92-93 

names 16-17, 25, 151 

random-access text file 82-89 

sequential text file 49-71 

text file 48 

file buffer 43, 124 

FILE NOT FOUH) 118 

FILE LOCKED 120 

FILE TYPE MISMATCH 121 

floating point BASIC: 

see Applesoft BASIC 
FP 28-29 



GET 51 

greeting program 13-14 
renaming 45 

-H- 

HELLO program 13 
hexadecimal notation 24 
HIMEH: 12, 141 

1/0 devices 100 

I/O ERROR 119 

I (Input) parameter 42 
Immediate-execution rode 31-48 

"IN USE" light 7, 18 
IN# 11, 100-102, 157 

INIT (INITialUe) 13, 31, 151, 

166 

INPUT 51 

Input/Output control Block (IOB) 

94-98 
input registers 

DOS 101, 104 

Monitor 101, 103 
Input (I) parameter 42 
installing the DISK II 2-4 
INT 28-29, 156 
Integer BASIC 28-29 
Interface circuit schematics 145 

-J- 

J: see 1, (length) parameter 
JMP (jump) 93 

-K- 

kick: see booting 

-L- 

LAHCUAGE NOT AVAILABLE 115 

L (length) paraneter 
vith BSAVE 92, 150 
with OPEN 88, 126, 150 

length (L) paraneter 

of-binary-file 92 

of record 88, 126 
LOAD 16, 25-26, 153 
LOCK 35, 154 
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-M- 

machine-language files 92-93 

MAKE TEXT 61-64 

MASTER CREATE 44-46 

water diskettes 44-46 

MAXFILES 31, 43-44, 155-156 

memory requirements 13, 140 

memory usage and map 140 

MON 42*43, 155 

Monitor mode 50 

Monitor I/O registers 101, 103 

MUFFIN program 192-194 



NO BUFFERS AVAILABLE 121 
NOMON 42-43, 155 
NOT DIRECT COMMAND 122 
notation 148-150 



-o- 



L6I 



(output) parameter 

with MON 42 

with NOMON 42 

ONERR GOTO 114 
OPEN 49-71, 158, 

output registers 

DOS 101, 104 

Monitor 101, 103 
overwriting 63-64, 69 

-P- 

p: see relative-field position 

(R) parameter 
P, control 103 
POSITION 66-68, 125, 159-160 
PR# 11, 100-102, 157 
PRINT (with CTRL-D) 29*31, 50 
PROGRAM TOO LARGE 29 

prompt characters 11, 36 
PROMS 174-176 

quotation marks 30 



-R- 

R parameter 

with EXEC 79 

with POSITION 67-69, 125 

with READ 67-68, 150 

with WRITE 67-68, 150 
RUTS subroutine 94-98 
random-access text file 82-89 

creating and retrieving 82*85, 
170 

differences from sequential 82 

sample programs 82-87 
RANGE ERROR 116 
READ 

with random-access text files 
88-89, 137, 162 

with sequential text files 
49-71, 136, 159 

read or write a track 
or sector 94-98 

record 82, 126 

record number (R) parameter 82-86 

relative-field position 

(R) parameter 67-69 
RENAME 17 » 153 
RESET 11, 18, 149, 166 
RETRIEVE TEXT 65-66 
RETURN 11, 12, 149 
REIURN character 51 
ribbon cable 2-4 
RUN 25-26, 153 

_$- 

s: see S (slot) parameter 
S (slot) parameter 22, 149 
SAVE 15, 25-26, 152 
schematics 145-146 
sector 16, 94, 124 

allocation order 135 

13 to 16 conversion 192-194 

format 127-128 
sequential text file 49-71 

creating and retrieving 49-71, 
167-168 

EXEC 76, 169 

sample programs 49-71 
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; -t 

Si -4 

5l -4 

E 4 

E ■! 

SI •! 

E >i 

E •! 

E I 

E •: 

E •« 

E -1 

E -t 

E si 

E <i 

E ■< 

E il 

E M 

E it 

E -< 



slave diskettes 13, 141 

slots 3 

slot (S) parameter 22, 149 

syntax 148-1 50 

SYNTAX ERROR 120 

System Master diskette lfl, 13-14 

-T- 

text file, random-access: 
see random-access text file 

text file, sequential: 
see sequential text file 

TRACE 44 

track allocation order 135 

track bit map 124, 133-134 

track/sector list 124, 128-129 

tracks 94, 124 

turnkey system 34-35, 167, 177 

_u- 

UNLOCK 35, 154 
unpacking 2 

-V- 

v: see V (volume) parameter 

V (volume) parameter 23, 149 

VERIFY 35-36, 154 

VOLUME MISMATCH 118-119 

volume nunfcer: see volume parameter 

volume (V) parameter 23, 149 

VTOC (volume table of contents) 

132-133 

-w- 

wildcard characters 184, 193 
WRITE 

with random-access text files 

88-89, 126, 162 
with sequential text files 

49-71, 124-125, 159 
write protecting 36—37 
WRITE PROTECTED 116 



-X-Y-Z- 

Y -register 94-95 
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DOS MESSAGE INDEX 



ERROR t 


MESSAGE 


9 


DISK FULL 


5 


END OF DATA 


10 


FILE LOCKED 


6 


FILE NOT FOUND 


13 


FILE TYPE MISMATCH 


8 


I/O ERROR 


1 


LANCUACE NOT AVAILABLE 


12 


NO BUFFERS AVAILABLE 


15 


HOT DIRECT COMMAND 


14 


PROGRAM TOO LARGE 


2,3 


RANGE ERROR 


11 


SYNTAX ERROR 


7 


VOLUME MISMATCH 


4 


WRITE PROTECTED 




PAGES 



120 
53, 
118. 
35, 

17. 
35, 
22, 
28, 
43, 
48, 
29, 
92, 
10. 
23, 
37, 



58, 
160 

67. 

18, 

48, 

26. 

115, 

121, 

122 

122 

116 

26, 

118- 
116- 



67, 68, 70, 79, 86, 1 17- 

, 161 

120 

26, 36, 46, 59, 118, 1H 
121, 152 
36, 119, 154 

153 

156 



28, 79, 92, 120 

119 
117 



PROGRAM INDEX 



PROGRAM 



FACLS 



Greeting (HELLO) 
COUNT 

CATALOC-Creeting 
COLOR DEMO 
ANIMALS 

COPY 

MASTER CREATE 

EXEC DEMO 

CAPTURE 

RANDOM, APPLE PROMS 

CHAIN 
FID 

MUFFIN 



13-14 

15 

29-30 
34-35 
37 

38-40 
44-46 
74-75 
76-77 

86-88 

106-107 
184-189 
192-194 
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DOS 

QUICK REFERENCE CARD 

On this card, DOS commands are grouped Into 
these 5 categories: 



COMMAND PARAMETERS 

An error message is given If a DOS command 
quantity is too large or too small. 



HousekeeoinR comnands: 
1NIT LOAD DELETE 


VERIFY 

HON 
NOMON 


HAXFILES 


ALL FILES 
Parameter 


As shown 


Mln 


Max 


CATALOG RUN LOCK 
SAVE RENAME UNLOCK 


Slot 

Drive 

Volume 


,Sl 

.Dd 
.Vv 


SI 

Dl 


S7 
D2 
V254 



FP TNT PR* IN* 


CHAIN 


Sequential Text File Commands: 





OPEN 
CLOSE 



READ 
WRITE 



Random-Access Text File C 



APPEND 
POSITION 

nds; 



EXEC 



OPEN 



CLOSE 



BEAD 



Machinf-Langviage Fi U- CorinMn<ls : 



BLOAD 



BRUN 



WK1TK 



BSAVB 



NOTATION AND SYNTAX 

A "parameter" Is a capital letter, usually 
followed by a number (shown here by a 
lower-case letter), which gives additional 
information for executing a command. 
Multiple parameters may appear in any 
order, but must be separated fron each 
other by a comma* A parameter shown in 
square brackets [like this] Is optional. 

A file name (shown here by X ) must immedi- 
ately follow its command word. File names 
must begin with a letter; only the first 
30 characters are used* A comma separates 
a file name from a following parameter* 

CTRL-D (type D while holding down CTRL key) 
is used in PRINT statements to Indicate the 
start of a deferred-execution DOS command. 
Integer BASIC example: 

[0 DS - "*' : REM "CTRL-D" 

20 PRINT DS; "CATALOG" 
Applesoft BASIC example: 

10 DS = CHR$(M : REM CTRL-D 

20 PRINT DS; "CATALOG" 

The term "BASIC" alone is used to mean either 
Integer BASIC or Applesoft BASIC. The term 
"file" alone means any type of diskette file. 



* Using V0 is like omitting the Vv parameter; 
the diskette's volume number is Ignored. 
Smallest volume number INIT will actually 
assign to a diskette is 1* 



SEQUENTIAL TEXT FILES 

Parameter As shown Kin Max 



Byte ,Bb 

Relative Field * .Rp 



B32767 
R32767 



* With EXEC, always relative to field 0. 



RANDOM-ACCESS TEXT FILES 



Parameter 



As shown 



Min 



Max 



Record Length 
Record Number 



BINARY FILES 



.Rr 



LI 



L32767 
R32767 



Parameter 



As shown 



Min 



Max 



Starting Address 
Number of Bytes 



DOS COMMANDS 



,Aa 



A0 
LI 



A65535 
A32767 



Command 



Quantity 



As shown 



Min 



Max 



PR# 

mi 

HAXFILES 



slot 
slot 
file buffers 



PR# s n§9 PR*7 

IN# s IN#fl IN#7 

HAXFILES n n-1 n-16 



Commands use Slot 
when changing to j 



or Drive parameters only 
different Slot or Drive. 



If a command omits the Volume parameter or 
uses V0 . the diskette's volume number is 
ignored- A command that uses the Volume 
parameter Vv will not be executed unless 
the diskette's volume number is v • 



HOUSEKEEPING COMMANDS 

INIT X (,VvJ [,Sft] f.Ddl 

Initialises a blank diskette to form a slave 
diskette* Assigns greeting program name X 
and volume number v (if specified)* SAVEs 
the BASIC program currently in memory, under 
file nam X • 



CATALOG (,Ss| (,Dd) 

Displays volume number and all files on a 
diskette, with each file's type and sector 
length, * indicates a LOCKed file. 



Typfr 



Description 



(How < reared) 



I Integer BASIC program file 

A Applesoft BASIC program fil 

T Text File (OPEN, 

B Binary memory-image file 



(SAVE) 

\ (SAVE) 

then WRITE) 

(BSAVE) 



SAVE X [ t SsJ l.DdJ [,VvJ 

Stores current BASIC program onto diskette, 
under file name X . Overwrites any previous 
file of same type and name, without warning. 



LOAD X (,Ss) f,DdJ l,VvJ 

Loads BASIC program file X into memory, 
after clearing memory and (if necessary) 
changing to the correct BASIC. 



RUN X I.Ss) I,Dd] l,VvI 
LOADs BASIC program file 
then RUKs the program. 



RENAME X, Y [,Ss) (,Dd] [,VvJ 
Changes a diskette file's name from X 



to 



DELETE X (,Ss) ( ,Dd 
Erases file X from 



I.VvJ 
the dl*keue. 



LOCK X ( t Sm) UDdl UVv] 

Locks file X against accidental rhange or 

deletion. LOCKed file stlmwn In CATALOG by * 



UNLOCK X US*] l< Dd ' l* Vv ' 
Unlocks previously LOCKed (U« 
to allow change or delft lun. 



VERIFY X 1,59] f.Dd! I,Vv] 
Checks file X for internal consistency. 
If X was saved without error, no message 
Is given. 



HON [ t C] Ml [.01 

Causes display of disk Commands ( C ), 
Input from the disk ( I ) t and Output 
to the disk ( ). With no parameters, 
MON is ignored. 



HOHOK (,C1 LI) [,0J 

Cancels display of disk Comn;inds ( C )* 
input from the disk ( I ), and Output 
to the disk ( ). With no parameters, 
NOMON is Ignored. 



MAXFILES n 

Reserves n file buffers for disk Input and 
output (booting reserves 3 file buffers). 
Use before LOADing or RUNnlng a program- 



ACCESS COMMANDS 



FP [,Ss] [,DdJ I,Vv] 

Puts system into Applesoft BASIC, 

erasing any program In memory* 



INT 

Puts system into Integer BASIC, 

erasing any program in memory. 



PRl s 

Sends subsequent output to slot s * Boots 
disk if slot s contains disk controller 
card. PR#0 sends output to TV screen again. 



IHf s 

Takes subsequent input from slot s . Boots 
disk if slot s contains disk controller 
card* IN#0 takes Input from keyboard again. 



CHAIN Y |,Ssl [,DdJ [,Vvl 

RUNs Integer BASIC program file Y » but does 
not clear variables developed by previous 
Integer BASIC program. 



SEQUBITIAL TEXT RLE COMMANDS 

OPEN X [,Ss] [,Dd) |,Vv] 

Opens or creates sequential text file X , 
allocates one file buffer and prepares to 
WRITE or READ from beginning of file. 



CLOSE (XI 

Completes WRITE X, if necessary, and de- 
allocates file buffer assigned to text file 
X . Without file name. CLOSE* all OPEN files 
(except an EXEC file). 



WRITE X (,Bbl 

Subsequent PRINTs send characters to 
sequential text file X - WRITEing begins 
at current file position or (if specified) 
at byte b . Cancelled by any DOS command, 



READ X [.Bb) 

Subsequent INPUTs and GETs take response 
characters from sequential text file X * 
READing begins at current file position or 
(If specified) at byte b ■ INPUT response 
is one field (all characters to next 
RETURN). Cancelled by any DOS coemand. 



APPEND X (,Sa) (,Dd) f,Vv] 
Opens existing sequential text file X 
similar to OPEN, but prepares to WRITE 
at the end of the file* 



POSITION X, Rp 

In OPEN sequential text file X , subsequent 
READ or WRITE will proceed from p-th field 
i_oi inwi >\£ miTwii fill position! 



EXEC X I.Rp) I,Ss) l.Dd) [.VvJ 
Executes successive fields in sequential 
text file X as if typed at keyboard. 
With Rp parameter, execution begins with 
p-th field. Fields may include numbered 
BAH Ht program Lines and direct-execution 
BASIC <*r DOS commands to control the Apple. 



RANDOM-ACCESS TEXT FILE 
COMMANDS 

OPEN X. L] ( # Ss) [»Ddl [,Vvl 

Opens or creates random-access text file X , 
allocates one file buffer, and defines record 
length as J bytes. Prepares to WRITE or READ 
from beginning of Record 0* Sane Length param- 
eter must be used each time file X is OPENed- 



CLOSE IX] USs] (,Dd) [ t Vv) 
Completes WRITE X, If necessary, and de- 
allocates file buffer assigned to text file 
X . Without file name, CLOSEs all OPEN files. 



WRITE X (,Rr] [,Bb] 

Subsequent PRINTs send characters to random- 
access text file X . With no parameters, 
WRITEing begins at current file position. 
With Rr parameter alone, WRITEing starts at 
byte of Record r . With Bb parameter, 
WRITE starts at byte b of current or spec- 
ified Record* Cancelled by any DOS command. 



READ X [,Rr) [,Bb) 

Subsequent INPUTS and GETs take response 
characters from random-access text file X . 
With no parameters, READing starts at cur- 
rent file position. With Rr parameter 
alone, READing starts at byte of Record r 
With Bb parameter, READing starts at byte 
b of current or specified Record. INPUT 
response is one field (all characters to 
next RETURN). Cancelled by any DOS command. 

M ACH INE-LANGUAGE FILE 
COMMANDS 

BSAVE X. Aa, Lj [ # SsJ (,Ddl (,Vv) 
Stores on diskette, under file name X , 
the contents of J memory bytes starting 
at address a t 



BLOAD X [,Aa] USs] l,Dd) I.Vv] 
Loads binary file X into same memory 
locations from which file was BSAVEd or 
(if specified) starting at address a . 

BRUN X (,Aa) (,Ssl (,Dd) { t Vv| 

BLOADs binary file X , then jumps <JMP) 

to loaded file's first memory address. 
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